Controle de versão, suporte e mudanças significativas de políticas para o Microsoft Graph

Este artigo descreve o suporte e as alterações significativas de políticas do Microsoft Graph e as versões da API Microsoft Graph disponível no momento.

Informações de política e substituição de suporte

O Microsoft Graph segue a Política de Ciclo de Vida da Microsoft.

À medida que novas versões das APIs REST do Microsoft Graph forem lançadas, as versões anteriores serão desativadas. A Microsoft declara uma versão como preterida com antecedência de pelo menos 24 meses antes de preteri-la. Da mesma forma, para APIs individuais que atingiram a disponibilidade geral (GA), a Microsoft declara uma API como preterida pelo menos 24 meses antes de removê-la da versão GA.

Para os SDKs do Microsoft Graph, apenas a versão principal mais recente de uma determinada biblioteca tem suporte e é atualizada com novos recursos, correções de bugs e soluções alternativas. A versão principal que precede a versão mais recente tem suporte por 12 meses a partir da data de lançamento da versão principal mais recente, apenas para correções de segurança. Recomendamos que você atualize para a versão mais recente dos SDKs sempre que possível.

Quando incrementamos a versão principal da API (por exemplo, de v1.0 para v2.0), anunciamos que a versão atual (neste exemplo, v1.0) foi imediatamente preterida e não daremos mais suporte a ela 24 meses após o anúncio. Abrimos exceções a esta política para problemas de segurança do serviço ou confiabilidade da integridade.

Quando uma API é marcada como preterida, é altamente recomendável que você migre para a versão mais recente assim que possível. Em alguns casos, anunciaremos que novos aplicativos terão que começar a usar as novas APIs pouco tempo depois que as APIs originais forem preteridas. Nesses casos, apenas os aplicativos ativos que usam atualmente as APIs preteridas podem continuar a usá-las.

Contrato de API e alterações não compatíveis com versões anteriores

O Microsoft Graph tem um log de alterações entre as versões. Essas alterações estão listadas no log de alterações do Microsoft Graph. À medida que novas funcionalidades e dados são adicionados ao Microsoft Graph, incrementamos o número de versão da API para quaisquer alterações não compatíveis com versões anteriores na API.

Os seguintes são exemplos de alterações não compatíveis com versões anteriores:

• Mudanças na URL ou solicitação/resposta fundamentais associadas ao recurso
• Remoção, renomear ou alterar o tipo de uma propriedade declarada
• Remoção ou renomeação de APIs ou parâmetros de API
• Adição de um cabeçalho de solicitação obrigatório

A seguir há exemplos de alterações compatíveis com versões anteriores:

• Adição de propriedades que são anuláveis ou têm um valor padrão
• Adição de um membro a uma enumeração
• Remover, renomear ou alterar o tipo de uma extensão aberta
• Remover, renomear ou alterar o tipo de uma anotação
• Introdução de paginação a coleções existentes
• Alterações de códigos de erro
• Alterações à ordem das propriedades
• Alterações no formato ou no comprimento de cadeias de caracteres opacas, como IDs de recurso

Observação: Ao longo do tempo, atualizamos a lista de alterações compatíveis com versões anteriores. Se você gerar seus próprios proxies de cliente (como clientes WCF), nossa orientação é que os aplicativos cliente devem estar preparados para receber propriedades e tipos derivados definidos anteriormente pelo serviço da API do Microsoft Graph. A API do Microsoft Graph segue a orientação descrita na seção Controle de Versão de Modelo nas diretrizes da API REST da Microsoft.

Versões

As seguintes versões da API Microsoft Graph estão disponíveis atualmente.

Versão beta

Em geral, as APIs são lançadas na versão beta e são acessíveis no ponto de extremidade https://graph.microsoft.com/beta. Para obter a documentação da API beta, veja Referência de ponto de extremidade do Microsoft Graph beta. Espere alterações significativas e preterimento de APIs na versão beta regularmente. Não há suporte para o uso de APIs beta em aplicativos de produção.

Não damos nenhuma garantia de que um recurso beta será promovido para a versão atual. Quando a equipe da API do Graph acredita que um recurso beta está pronto para disponibilidade geral, adicionamos esse recurso à versão atual mais recente. Se a promoção do recurso resultar em uma alteração significativa para a versão atual, o número de versão será incrementado, com a nova versão se tornando a versão atual.

Versão atual

A versão atual do Microsoft Graph é a 1.0. Essas APIs podem ser acessadas no https://graph.microsoft.com/v1.0 ponto de extremidade. A versão v1.0 da API do Graph contém recursos que geralmente estão disponíveis e prontos para uso em produção. Para obter a documentação da API v1.0, consulte a referência do ponto de extremidade do Microsoft Graph v1.0.

Status da visualização

Uma API ou recurso no Microsoft Graph é rotulado como "(versão prévia)" para indicar que seu comportamento é exclusivo no ponto de extremidade beta.

O comportamento da maioria dos recursos e das APIs na versão v1.0 está em paridade com a versão beta. Algumas APIs são marcadas como "prévias" por um dos seguintes motivos:

• As APIs estão disponíveis apenas na versão beta
• O comportamento das APIs é diferente na versão beta e na v1.0

Como qualquer outra API no ponto de extremidade beta, podemos introduzir alterações significativas em APIs marcadas como visualização sem aviso prévio. Não acesse APIs do ponto de extremidade beta em aplicativos de produção.

Observação: As APIs podem estar em versão prévia mesmo quando o recurso ou o produto em si está em disponibilidade geral.

Versões preteridas e sem suporte

No momento, nenhuma versão do Microsoft Graph foi preterida ou não tem suporte.

Termos de uso

Ao usar as APIs do Microsoft Graph, você concorda com os Termos de Uso das APIs da Microsoft.

Seus comentários são importantes para nós. Conecte-se conosco no Microsoft Q&A. Marque suas perguntas com [microsoft-graph-*]