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 forem lançadas novas versões das APIs REST do Microsoft Graph, as versões anteriores serão descontinuadas. 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 com pelo menos 24 meses de antecedência para removê-la da versão ga.
Para os SDKs do Microsoft Graph, apenas a versão principal mais recente de qualquer biblioteca especificada é suportada e atualizada com novas funcionalidades, correções de erros e soluções alternativas. A versão principal que precede a versão mais recente é suportada durante 12 meses a partir da data de lançamento da versão principal mais recente, apenas para correções de segurança. Recomendamos que atualize para a versão mais recente dos SDKs sempre que possível.
Quando incrementamos a versão principal da API (por exemplo, da v1.0 para a v2.0), anunciamos que a versão atual (neste exemplo, v1.0) foi imediatamente preterida e deixaremos de a suportar 24 meses após o anúncio. Podemos fazer exceções a essa política em questões de segurança de serviço ou confiabilidade de 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, iremos anunciar que as novas aplicações terão de começar a utilizar as novas APIs pouco tempo depois de as APIs originais serem preteridas. Nesses casos, apenas os aplicativos ativos que usam atualmente as APIs preteridas podem continuar a usá-las.
Contrato de API e alterações compatíveis com não estorno
O Microsoft Graph tem um log de alterações entre as versões. Estas alterações estão listadas no registo de alterações do Microsoft Graph. À medida que as novas funcionalidades e dados são adicionados ao Microsoft Graph, incrementamos o número da versão da API para quaisquer alterações compatíveis com o estorno à API.
Seguem-se exemplos de alterações compatíveis com não estorno:
- 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
Nota: Ao longo do tempo, atualizamos a lista de alterações retrocompatíveis. 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. A utilização de APIs beta em aplicações de produção não é suportada.
Não damos nenhuma garantia de que um recurso beta será promovido para a versão atual. Quando a equipa da Microsoft Graph API acredita que uma funcionalidade beta está pronta para disponibilidade geral, adicionamos essa funcionalidade à versão atual mais recente. Se a promoção da funcionalidade resultar numa alteração interruptiva da versão atual, o número da versão será incrementado, com a nova versão a tornar-se a versão atual.
Versão atual
A versão atual do Microsoft Graph é a 1.0. Estas APIs estão acessíveis no https://graph.microsoft.com/v1.0 ponto final. A versão da Microsoft Graph API v1.0 contém funcionalidades que estão geralmente disponíveis e prontas para utilização em produção. Para obter a documentação da API v1.0, veja Microsoft Graph v1.0 endpoint reference (Referência do ponto final do Microsoft Graph v1.0).
Status da visualização
Uma API ou funcionalidade no Microsoft Graph é identificada como "(pré-visualização)" para indicar que o respetivo comportamento é exclusivo no ponto final 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 estão marcadas como "pré-visualização" por um dos seguintes motivos:
- As APIs só estão disponíveis na versão beta
- O comportamento das APIs é diferente em beta do que v1.0
Tal como qualquer outra API no ponto final beta, podemos introduzir alterações interruptivas às APIs marcadas como pré-visualização sem aviso prévio. Não aceda às APIs a partir do ponto final beta nas aplicações de produção.
Nota: As APIs podem estar em pré-visualização mesmo quando a funcionalidade ou o próprio produto está geralmente disponível.
Versões preteridas e sem suporte
Atualmente, nenhuma versão do Microsoft Graph foi preterida ou não é suportada.
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-*]