Esta página descreve como fazer o controlo de versões da sua API e como implementar várias versões.
Recomendações para gerir versões da API
Ao gerir as versões da API, considere estas recomendações:
- Quando quiser introduzir uma alteração incremental, mas não destrutiva, mantenha a versão da API constante e implemente-a na API existente.
- Quando introduz uma alteração interruptiva na sua API, aumente a versão da API.
- Para proteção adicional, incremente também a versão da aplicação do App Engine e, em seguida, implemente a nova versão da API nessa nova versão da aplicação do App Engine. Isto permite-lhe usar a flexibilidade integrada do App Engine para alternar rapidamente entre as versões do App Engine e servir a partir das versões antigas em funcionamento se tiver problemas inesperados.
A tabela seguinte é uma ilustração da cascata de versões da API de back-end para diferentes versões da aplicação do App Engine.
| Versão da aplicação | Versão da API de back-end |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
Conforme mostrado na tabela, as atualizações incrementais e não destrutivas da v1 da API são implementadas, cada uma substituindo a versão anterior. Quando são introduzidas alterações significativas, a versão da API é incrementada para v2 e é implementada numa nova versão da aplicação do App Engine. Isto permite-lhe voltar à versão anterior das aplicações, se necessário.
Na tabela, repare que a versão 2 da aplicação suporta a versão v1 mais recente e a nova versão v2 da sua API. Se não eliminar o código v1 existente do seu projeto, quando implementar o projeto, v2 e vl (n) da sua API são implementados na versão 2 da sua aplicação.
Implementação em várias versões da aplicação
Quando implementa a API de back-end, implementa-a no ID do projeto do
Google Cloud projeto que criou para a sua API e também tem de
especificar a versão do App Engine para a qual faz a implementação.
Especifica a versão da app do App Engine na linha de comandos quando
implementa a sua app.
A versão da app do App Engine não é o mesmo que o número da versão
da API de back-end, que especifica no argumento version do
decorador @endpoints.api.
Conforme mostrado na figura anterior, pode implementar várias versões da API na mesma versão do App Engine. Além disso, pode ter muitas versões do App Engine para uma aplicação.
Aceder a versões da API implementadas numa versão de publicação
A primeira versão do App Engine para a qual implementa a sua API é a versão de publicação. Esta versão é executada no URL
http://YOUR_PROJECT_ID.appspot.com onde
YOUR_PROJECT_ID representa o seu Google Cloud
ID do projeto. Pode aceder a todas as versões da API implementadas nessa versão da aplicação do App Engine através desse URL.
A versão de publicação permanece a mesma até a alterar explicitamente na Google Cloud consola.
Aceder a versões da API implementadas numa versão da aplicação que não está em serviço
Se precisar de aceder a versões da API que não estão implementadas na versão do App Engine atualmente em serviço, usa um URL específico da versão, semelhante ao seguinte:
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
Substitua VERSION pela versão do App Engine e YOUR_PROJECT_ID pelo ID do Google Cloud projeto. Por exemplo, suponhamos que a versão de publicação do App Engine é 1, mas quer aceder a uma versão da API implementada na versão 2. Usaria este URL: https://2-dot-YOUR_PROJECT_ID.appspot.com.
Para mais detalhes, consulte a documentação do App Engine.
Aceder a versões da API implementadas em serviços que não são de publicação (anteriormente módulos)
Se precisar de aceder a versões da API que não estejam implementadas no serviço do App Engine predefinido, pode usar um URL específico do serviço com a sintaxe de ponto da seguinte forma:
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
Para mais detalhes, consulte a documentação do App Engine.