Esta página descreve como usar uma especificação OpenAPI 3.x ao configurar os Endpoints.
Antes de começar
- Confirme que tem uma instância do Endpoints configurada com uma especificação OpenAPI 2.0.
- Instale a CLI
gcloud. Para mais informações, consulte o artigo Instale a CLI Google Cloud.
Modifique a configuração dos Endpoints para usar a OpenAPI 3.x
Conclua os passos seguintes para modificar uma configuração de pontos finais da OpenAPI 2.0 existente para usar a OpenAPI 3.x.
Veja o histórico de implementação
Para ver o histórico de implementação:
Na Google Cloud consola, aceda à página Endpoints > Services.
Na lista de projetos, selecione o seu projeto.
Se tiver mais do que uma API, selecione uma API na lista.
Para ver uma lista de implementações de configuração de serviços, clique no separador Histórico de implementações. A lista apresenta:
- O ID de configuração.
- A data em que a configuração do serviço foi implementada.
- Quem implementou a configuração do serviço.
Veja a configuração do serviço
No separador Histórico de implementação, selecione a implementação mais recente na lista. O conteúdo do ficheiro de configuração do serviço implementado é apresentado.
Converta o documento OpenAPI para OpenAPI 3.x
Converta o seu documento OpenAPI 2.0 para OpenAPI 3.x. Pode usar uma ferramenta que suporte esta conversão para o formato OpenAPI 3.x. Por exemplo, o Swagger Editor oferece uma utilidade de conversão.
Após a conversão inicial para o OpenAPI 3.x, aplique manualmente quaisquer alterações adicionais ao documento para se alinhar com o OpenAPI 3.x e garantir a compatibilidade com as extensões e as funcionalidades do Endpoints.
A tabela seguinte descreve as alterações necessárias:
| Funcionalidade | OpenAPI 2.0 | OpenAPI 3.x | Descrição da alteração |
|---|---|---|---|
| Chave da API | securityDefinitions |
securitySchemes |
As chaves da API usam o suporte de chaves da API OpenAPI pronto a usar. Normalmente, as ferramentas de conversão processam esta situação automaticamente. Não são necessárias alterações manuais. |
| Autenticação JWT | x-google-audiences, etc. |
x-google-auth |
Nas extensões OpenAPI 2.0, define a configuração OAuth com extensões individuais numa instância securityDefinition.
As ferramentas de conversão convertem a instância do esquema de segurança em #/components/securitySchemes e deixam as extensões.
Modifique manualmente estas extensões para que sejam filhas de x-google-auth e remova o prefixo x-google-. Os valores permanecem inalterados. |
| Quota | x-google-management, x-google-quota |
x-google-api-management, x-google-quota |
Nas extensões OpenAPI 2.0, define métricas e quotas em
x-google-management e anexa-as com
x-google-quota. As ferramentas de conversão mantêm estas extensões. Mova manualmente as métricas e a configuração de quota de
x-google-management para x-google-api-management.
Altere a configuração para usar chaves YAML e remova valueType, metricKind e unit.
Remova metricCosts das instâncias de
x-google-quota. |
| Back-ends | x-google-backend |
x-google-api-management, x-google-backend |
Nas extensões OpenAPI 2.0, define back-ends em
x-google-backend e a configuração aplica-se onde
está definida. Nas extensões OpenAPI 3.x, define o back-end em
x-google-api-management e, em seguida, aplica-o com
x-google-backend. As ferramentas de conversão mantêm esta extensão
no lugar. Mova manualmente a configuração para
x-google-api-management. Modifique as instâncias de
x-google-backend para fazer referência a essa configuração. |
| Pontos finais | x-google-endpoints |
x-google-endpoint, servers |
Nas extensões OpenAPI 2.0, define a configuração dos pontos finais em
x-google-endpoints. Nas extensões OpenAPI 3.x, usa x-google-endpoint, mas é uma extensão em servers e não na raiz. As ferramentas de conversão mantêm
esta extensão no lugar. Mova-o manualmente para servers e
remova o campo name. Por exemplo:
# OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True |
| Nomes das APIs | x-google-api-name |
x-google-api-management |
Nas extensões OpenAPI 2.0, define os nomes das APIs em
x-google-api-name. Nas extensões OpenAPI 3.x, usa um campo apiName em x-google-api-management.
Mova manualmente esta configuração para x-google-api-management. |
| Permitir todo o tráfego | x-google-allow |
NÃO SUPORTADO | Remova-o do documento OpenAPI. Os Endpoints não suportam esta funcionalidade no OpenAPI 3.x. |
Volte a implementar a configuração do serviço
Sempre que alterar algo no seu documento OpenAPI, certifique-se de que o implementa novamente para que o Endpoints tenha a versão mais recente da configuração do serviço da sua API. Não precisa de voltar a implementar nem reiniciar o ESP se o tiver implementado anteriormente com a opção rollout definida como managed.
Esta opção
configura o ESP para usar a configuração do serviço implementada mais recente. Quando
especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar.
Para implementar o seu documento OpenAPI:
Mude o diretório para a localização que contém o seu documento OpenAPI.
Valide o ID do projeto devolvido pelo comando seguinte para se certificar de que o serviço não é criado no projeto errado.
gcloud config list projectSe precisar de alterar o projeto predefinido, execute o seguinte comando e substitua YOUR_PROJECT_ID pelo Google Cloud ID do projeto no qual quer criar o serviço::
gcloud config set project <var>YOUR_PROJECT_ID</var>Execute o seguinte comando e substitua YOUR_OPENAPI_DOCUMENT pelo nome do documento OpenAPI que descreve a sua API:
gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>
Quando executa o comando anterior pela primeira vez, o Service Management cria um novo serviço de Endpoints no projeto predefinido com um nome que corresponde ao texto especificado no campo host no seu documento OpenAPI e carrega a configuração do serviço.
À medida que cria e configura o serviço, a gestão de serviços envia informações para o terminal. Após a conclusão com êxito, é apresentada uma linha semelhante à seguinte, que apresenta o ID de configuração do serviço e o nome do serviço:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
No exemplo anterior, 2017-02-13r0 é o ID da configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o nome do serviço.
Após uma implementação bem-sucedida, pode ver a API na página Endpoints > Serviços na Google Cloud consola.
Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de implementação da configuração dos pontos finais.