Nesta página, você aprende a fazer o controle de versões da API e como implantar em várias versões.
Recomendações para o gerenciamento de versões de API
No gerenciamento das suas versões de API, considere estas recomendações:
- Quando você quiser introduzir uma mudança incremental, mas não separável, mantenha a versão da API constante e implante sobre a API existente.
- Ao apresentar uma alteração interruptiva na API, incremente a versão da API.
- Para ter proteção adicional, incremente a versão do aplicativo App Engine e implante a nova versão da API na nova versão do aplicativo App Engine. Isso permite que você use a flexibilidade integrada do App Engine para alternar rapidamente entre as versões do App Engine e utilizar as versões funcionais antigas caso ocorram problemas inesperados.
A tabela a seguir é uma ilustração das versões da API de back-end em cascata para diferentes versões do aplicativo App Engine.
| Versão do aplicativo | Versão da API de back-end |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
Conforme mostrado na tabela, são implementadas atualizações incrementais não interruptivas para a v1 da API, cada uma substituindo a versão anterior. Quando são introduzidas alterações interruptivas, a versão da API é incrementada para a v2 e ela é implantada em uma nova versão do aplicativo App Engine. Assim, é possível reverter para a versão anterior dos aplicativos se necessário.
Na tabela, a versão 2 do aplicativo é compatível com a v1 mais recente e com a nova v2 da API. Se você não excluir o código v1 atual do projeto, quando implantar o projeto, v2 e vl (n) da API serão implantados na versão 2 do aplicativo.
Como fazer a implantação em diversas versões do aplicativo
Ao implantar a API de back-end, implante-a no código do projeto do Google Cloud criado para sua API e especifique a versão do App Engine em que você quer fazer a implantação.
Especifique a versão do aplicativo App Engine no elemento <version> do arquivo /WEB-INF/appengine-web.xml. A versão do aplicativo do App Engine não é a mesma coisa que o número da versão da API de back-end, que você especifica no atributo version da anotação @Api.
Conforme mostrado na imagem acima, é possível implantar várias versões da API na mesma versão do App Engine. Também é possível ter várias versões do App Engine em um aplicativo.
Como acessar as versões da API implantadas em uma versão fornecida
A primeira versão do App Engine em que você implanta a API é a versão fornecida. Ela é executada no URL http://YOUR_PROJECT_ID.appspot.com, em que YOUR_PROJECT_ID representa o ID do projeto do Google Cloud. Use esse URL para acessar todas as versões de API implantadas na versão desse aplicativo do App Engine.
A versão de serviço permanece a mesma até que você a altere explicitamente no console do Google Cloud.
Como acessar versões da API implantadas em uma versão que não é de serviço
Se você precisar acessar versões da API que não foram implantadas na versão do App Engine atualmente fornecida, use um URL específico da versão desta maneira:
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
Substitua VERSION pela versão do App Engine e YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Por exemplo, se a versão fornecida do App Engine for 1, mas você quer acessar uma versão da API implantada na 2, use este URL: https://2-dot-YOUR_PROJECT_ID.appspot.com.
Para mais detalhes, consulte a documentação do App Engine.
Como acessar as versões da API implantadas em serviços não fornecidos (anteriormente módulos)
Se você precisar acessar versões da API que não foram implantadas no serviço padrão do App Engine, poderá utilizar um URL específico do serviço usando a sintaxe de ponto da seguinte maneira:
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
Para mais detalhes, consulte a documentação do App Engine.