Migrar para a versão 2.0 dos Cloud Endpoints Frameworks

O Cloud Endpoints Frameworks era anteriormente denominado Endpoints. Para distinguir as duas versões, esta página refere-se à nova versão como Endpoints Frameworks versão 2.0 e à versão mais antiga como Endpoints versão 1.0. Esta página descreve como migrar uma aplicação do Cloud Endpoints versão 1.0 para a versão 2.0 dos Frameworks do Endpoints. A migração consiste numa alteração da biblioteca e numa alteração da configuração da aplicação, mas não tem de fazer alterações ao código.

Vantagens

A versão 2.0 dos Endpoints oferece várias vantagens, incluindo:

  • Latência do pedido reduzida.
  • Melhor integração com as funcionalidades do App Engine, como domínios personalizados.
  • Novas funcionalidades de gestão de APIs.

A versão 2.0 do Endpoints Frameworks não afeta as interfaces da sua API. Os clientes existentes continuam a funcionar após a migração sem alterações ao código do lado do cliente.

Vista geral das funcionalidades

As seguintes funcionalidades são retrocompatíveis com a versão 1.0 dos Endpoints:

  • Protocolo JSON-REST, que é usado por todas as bibliotecas de clientes Google
  • Serviço de descoberta
  • Todas as funcionalidades de autenticação existentes (OAuth2/OpenID Connect)
  • Suporte da biblioteca cliente para clientes gerados
  • CORS (para autores de chamadas JavaScript que não usam a biblioteca de cliente JavaScript da Google)
  • Explorador de APIs

A divisão de tráfego está indisponível.

Funcionalidades atualmente excluídas

As seguintes funcionalidades estão indisponíveis. Se precisar de alguma destas opções, envie um pedido de funcionalidade.

  • Protocolo JSON-RPC, que é necessário para clientes iOS antigos. Para criar clientes iOS para a sua API do Endpoints Frameworks versão 2.0, recomendamos que use a biblioteca de cliente Objective-C das APIs Google para APIs REST.
  • ETags automáticos
  • Campos kind automáticos
  • Integração de IDE
  • fields respostas parciais
  • Criação automática do método da API PATCH

Migrar da versão 1.0 dos Endpoints

Para migrar da versão 1.0:

  1. Crie uma subpasta denominada /lib no diretório principal da sua aplicação.

  2. Instale a biblioteca a partir do diretório principal da sua aplicação:

     pip install -t lib google-endpoints --ignore-installed

  3. Remova as entradas - name: endpoints e version 1.0 do ficheiro app.yaml da sua aplicação na secção libraries. Por exemplo:

    libraries:
- name: endpoints   #Remove
  version: 1.0      #Remove

  4. Na secção libraries do ficheiro app.yaml, adicione o seguinte:

    libraries:
- name: pycrypto
  version: 2.6
- name: ssl
  version: 2.7.11

    Os frameworks de endpoints requerem estas versões das bibliotecas pycrypto e ssl.

  5. Na secção handlers do ficheiro app.yaml, altere a diretiva url de - url: /_ah/spi/.* para - url: /_ah/api/.*.

  6. No diretório raiz da sua aplicação, crie ou modifique um ficheiro denominado appengine_config.py para incluir o seguinte:

    from google.appengine.ext import vendor

vendor.add('lib')

  7. Verifique a string da versão da API. A string de versão, especificada no decorador @endpoints.api(version='v1', ...), aparece no caminho da API. Se especificar uma string de versão compatível com a norma SemVer, apenas o número da versão principal aparece no caminho da API quando implementa a API. Por exemplo, uma API denominada echo com a versão 2.1.0 teria um caminho como /echo/v2. Se atualizar a API echo para a versão 2.2.0 e implementar uma alteração retrocompatível, o caminho permanece /echo/v2. Isto permite-lhe atualizar o número da versão da API quando faz uma alteração compatível com versões anteriores sem interromper os caminhos existentes para os seus clientes. No entanto, se atualizar a API echo para a versão 3.0.0 (porque está a implementar uma alteração interruptiva), o caminho é alterado para /echo/v3.

  8. Volte a implementar a sua aplicação Endpoints Frameworks.

Validar uma nova implementação

Para verificar se a nova estrutura está a publicar tráfego:

  1. Envie alguns pedidos para a nova implementação.
  2. Visite a página do Cloud Logging para o seu projeto.

    Aceda à página do Explorador de registos

  3. Se os pedidos forem apresentados com caminhos que começam por /_ah/api, significa que a versão 2.0 dos Frameworks de Endpoints está a publicar a sua API. Os registos não devem apresentar pedidos com caminhos que comecem por /_ah/spi. Estes pedidos indicam que o proxy da versão 1.0 dos Endpoints continua a publicar pedidos.

Adicionar gestão de APIs

A versão 2.0 do Endpoints Frameworks adiciona funcionalidades de gestão de APIs, incluindo:

  • Gestão de chaves da API
  • Partilha de APIs
  • Autenticação do utilizador
  • Métricas da API
  • Registos da API

Para começar, aceda à página Começar a usar os frameworks de endpoints para Python.

Resolução de problemas

Esta secção descreve comportamentos irregulares comuns ao migrar para a versão 2.0 dos Frameworks de Endpoints e as soluções sugeridas.

A API devolve erros 404, mas o Explorador de APIs continua a listar as APIs corretamente

Tem de remover a configuração dos pontos finais da versão 1.0 antiga quando migrar para a versão 2.0 dos Frameworks de pontos finais. Se a configuração antiga ainda estiver presente na configuração da aplicação, o serviço Endpoints continua a tratar a app como uma app da versão 1.0. Pode ver pedidos nos registos do App Engine enviados para /_ah/spi, o que resulta em erros HTTP 404 enviados para o cliente.

  1. Remova as seguintes linhas do ficheiro app.yaml, se estiverem presentes:

    handlers:
- url: /_ah/spi/.*
  script: ...

  2. Certifique-se de que a secção handlers no ficheiro app.yaml tem o caminho correto:

    handlers:
# The endpoints handler must be mapped to /_ah/api.
- url: /_ah/api/.*
  script: ...

Mensagem de erro: ImportError: cannot import name locked_file

Isto acontece se as suas dependências contiverem uma versão da biblioteca oauth2client que não é compatível com o App Engine. Consulte o problema conhecido.