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

  • Artigo

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 removidas. 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 geralmente estão disponíveis (GA), a Microsoft declara uma API como preterida com antecedência de pelo menos 24 meses antes de removê-la da versão de GA. Para 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 anterior à 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) é imediatamente preterida e não vamos mais dar suporte a ela 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, 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.

Alterações compatíveis com o contrato de API e não compatíveis com o retorno

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 da versão da API para quaisquer alterações não compatíveis com o retorno na API.

Veja a seguir exemplos de alterações não compatíveis com o retorno:

  • 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 ao formato ou ao comprimento de cadeias de caracteres opacas, como IDs de recurso

Nota: ao longo do tempo, atualizaremos 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 tenha uma dependência de produção em APIs beta.

Não damos nenhuma garantia de que um recurso beta será promovido para a versão atual. Quando a equipe do Microsoft 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 de interrupção na versão atual, o número da versão será incrementado, com a nova versão se tornando a versão atual. Nossa comunidade de desenvolvedores pode postar solicitações de recursos no fórum de ideias da Plataforma de Desenvolvedores do Microsoft 365, incluindo solicitações de novos recursos e solicitações para promover APIs beta existentes para a versão atual.

Versão atual

A versão atual do Microsoft Graph é a 1.0. Exposta em https://graph.microsoft.com/v1.0, a versão da API Microsoft Graph v1.0 contém recursos que estão geralmente disponíveis e prontos para uso em produção. Navegue pela documentação para as APIs v1.0.

Status da visualização

Uma API ou um 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. "visualização" qualifica uma minoria de recursos e APIs em um dos dois casos a seguir:

  • Disponível somente em versão beta
  • Disponível na versão beta de forma diferente do que no v1.0

Assim como qualquer outra API no ponto de extremidade beta, as APIs marcadas na documentação como "(visualização)" podem sofrer alterações significativas sem aviso. Não acesse APIs do ponto de extremidade beta em aplicativos de produção.

Como exemplo, o treinamento de simulação de ataque é um recurso que geralmente está disponível para administradores no portal do Microsoft 365 Defender. Quando a API REST para treinamento de simulação de ataque fica disponível no Microsoft Graph apenas no ponto de extremidade beta, a documentação da API REST é rotulada como "(versão prévia)". O rótulo "(visualização)" se aplica à API REST e sua documentação no Microsoft Graph, mesmo que o serviço em si esteja disponível para o público geral.

Versões preteridas e sem suporte

Não há atualmente nenhuma versão preterida da Microsoft Graph.

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-*]