Controle de versão, suporte e mudanças significativas de políticas do Microsoft GraphVersioning, support, and breaking change policies for 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.This article describes the support and breaking change policies for Microsoft Graph and the versions of the Microsoft Graph API that are currently available.

Informações de política e substituição de suporteSupport policy and deprecation information

O Microsoft Graph segue a Política de Ciclo de Vida da Microsoft.Microsoft Graph follows the Microsoft Lifecycle Policy.

Conforme novas versões das APIs REST Microsoft Graph e SDKs do Microsoft Graph são lançadas, as versões anteriores são desativadas. A Microsoft declarará uma versão como preterida pelo menos 24 meses antes de retirar uma API ou um SDK.As new versions of the Microsoft Graph REST APIs and Microsoft Graph SDKs are released, earlier versions will be retired. Microsoft will declare a version as deprecated at least 24 months in advance of retiring an API or an SDK.

Quando incrementamos a versão principal da API (por exemplo, da v1.0 para a v2.0), estamos anunciando que a versão atual (neste exemplo, v1.0) está obsoleta imediatamente e não ofereceremos mais suporte 24 meses após o anúncio.When we increment the major version of the API (for example, from v1.0 to v2.0), we are announcing that the current version (in this example, v1.0) is immediately deprecated and we will no longer support it 24 months after the announcement. Podemos fazer exceções a essa política em questões de segurança de serviço ou confiabilidade de integridade.We might make exceptions to this policy for service security or health reliability issues.

Quando uma API é marcada como preterida, é altamente recomendável que você migre para a versão mais recente assim que possível.When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. Em alguns casos, anunciaremos que os novos aplicativos deverão começar a usar as novas APIs um pouco depois das APIs originais serem preteridas.In some cases, we will announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated. Nesses casos, apenas os aplicativos ativos que usam atualmente as APIs preteridas podem continuar a usá-las.In those cases, only active applications that currently use the deprecated APIs can continue to use them.

Contrato de API e alterações sem compatibilidade com versões anterioresAPI contract and non-backward compatible changes

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. Conforme nova funcionalidade e dados são adicionados ao Microsoft Graph, incrementaremos o número de versão da API para qualquer alteração à API não compatível com versões anteriores.Microsoft Graph has a log of changes across versions. These changes are listed in the Microsoft Graph Changelog. As new functionality and data is added to Microsoft Graph, we will increment the API version number for any non-backward compatible changes to the API.

A seguir há exemplos de alterações não compatíveis com versões anteriores:The following are examples of non-backward compatible changes:

  • Mudanças na URL ou solicitação/resposta fundamentais associadas ao recursoChanges to the URL or fundamental request/response associated with a resource
  • Remoção, renomear ou alterar o tipo de uma propriedade declaradaRemoval, rename, or change to the type of a declared property
  • Remoção ou renomeação de APIs ou parâmetros de APIRemoval or rename of APIs or API parameters
  • Adição de um cabeçalho de solicitação obrigatórioAddition of a required request header

A seguir há exemplos de alterações compatíveis com versões anteriores:The following are examples of backward compatible changes:

  • Adição de propriedades que são anuláveis ou têm um valor padrãoAddition of properties that are nullable or have a default value
  • Adição de um membro a uma enumeraçãoAddition of a member to an enumeration
  • Remover, renomear ou alterar o tipo de uma extensão abertaRemoval, rename, or change to the type of an open extension
  • Remover, renomear ou alterar o tipo de uma anotaçãoRemoval, rename, or change to the type of an annotation
  • Introdução de paginação a coleções existentesIntroduction of paging to existing collections
  • Alterações de códigos de erroChanges to error codes
  • Alterações à ordem das propriedadesChanges to the order of properties
  • Alterações no formato ou no comprimento de cadeias de caracteres opacas, como IDs de recursoChanges to the length or format of opaque strings, such as resource IDs

Observação: 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 do Microsoft REST.Note: Over time, we will update the list of backward compatible changes. If you generate your own client proxies (like WCF clients), our guidance is that your client applications should be prepared to receive properties and derived types not previously defined by the Microsoft Graph API service. Microsoft Graph API follows the guidance described in the Model Versioning section in the Microsoft REST API guidelines.

VersõesVersions

As seguintes versões da API Microsoft Graph estão disponíveis atualmente.The following versions of the Microsoft Graph API are currently available.

Versão betaBeta version

Exposto em https://graph.microsoft.com/beta, a versão beta da API Microsoft Graph contém recursos que estão atualmente na visualização.Exposed under https://graph.microsoft.com/beta, the Microsoft Graph API beta version contains features that are currently in preview. Para obter a documentação da API beta, veja Referência de ponto de extremidade do Microsoft Graph beta.For beta API documentation, see Microsoft Graph beta endpoint reference. Espere alterações significativas na versão beta regularmente.Expect breaking changes to the beta version from time to time. Não use uma dependência de produção em APIs /beta.Do not take a production dependency on /beta APIs.

Não damos nenhuma garantia de que um recurso beta será promovido para a versão atual. Quando a equipe da API Microsoft Graph acredita que um recurso beta está pronto para disponibilidade geral (GA), adicionaremos esse recurso à versão atual mais recente. Se a promoção do recurso resultar em uma alteração significativa de uma versão atual, o número da versão será incrementado e a nova versão se tornará a versão atual. Nossa comunidade do desenvolvedor pode postar solicitação de recursos no UserVoice, incluindo solicitações de novos recursos, bem como solicitações para promover APIs beta existentes para a versão atual.We make no guarantees that a beta feature will be promoted to the current version. When the Microsoft Graph API team believes that a beta feature is ready for general availability (GA), we will add that feature to the latest current version. If the promotion of the feature would result in a breaking change to the current version, the version number will be incremented, with the new version becoming the current version. Our developer community can post feature request on UserVoice, including requests for new features as well as requests to promote existing beta APIs to the current version.

Versão atualCurrent version

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. Você pode procurar a documentação das APIs 1.0 no sumário.The current version of Microsoft Graph is v1.0. Exposed under https://graph.microsoft.com/v1.0, the Microsoft Graph API /v1.0 version contains features that are generally available and ready for production use. You can browse the documentation for the v1.0 APIs in the table of contents.

Versões preteridas e sem suporteDeprecated and unsupported versions

Não há atualmente nenhuma versão preterida da Microsoft Graph.There are currently no deprecated versions of Microsoft Graph.

Termos de usoTerms of use

Ao usar as APIs do Microsoft Graph, você concorda com os Termos de Uso das APIs da Microsoft.By using the Microsoft Graph APIs, you agree to the Microsoft APIs Terms of Use.

Seus comentários são importantes para nós. Junte-se a nós no Stack Overflow. Marque suas perguntas com {MicrosoftGraph}.Your feedback is important to us. Connect with us on StackOverflow. Tag your questions with {MicrosoftGraph}.