Primeiros passos com a API Admin

Este guia foi criado para ajudar você a saber como usar a API Admin do Google App Engine para implantar um aplicativo Python de amostra no App Engine. Você pode usar o processo geral para descobrir como criar o código que gerencia e implanta seus aplicativos de maneira programática.

Neste guia, a amostra usada é um aplicativo Hello World simples que exibe o texto "Hello, World!" e está disponível no GitHub. Para autorização com o console do GCP, um ID do cliente OAuth e um navegador da Web são usados. Para demonstrar as etapas individuais do processo, os comandos cURL permitem enviar solicitações HTTP do seu terminal.

Objetivos

  • Ativar as APIs no projeto do console do GCP e criar credenciais do ID do cliente OAuth.
  • Receber tokens de acesso para autenticação no App Engine.
  • Usar a API Admin para implantar o aplicativo de amostra no App Engine.
  • Opcional: configurar o tráfego para a versão em que você implementou o aplicativo de amostra.

Antes de começar

Dica: para executar manualmente o aplicativo Hello World localmente, consulte o Início rápido do ambiente padrão do App Engine para Python.

Como configurar seu projeto do GCP

Ative a API Admin do Google App Engine e as APIs do Cloud Storage no projeto do GCP e, em seguida, configure as credenciais:

  1. Ative as APIs no console do GCP:

    Ativar as APIs

  2. No assistente, selecione um dos projetos na lista ou clique em Continuar para criar um projeto novo.

  3. Clique em Continuar para criar uma credencial de ID do cliente do OAuth:

    1. Na Tela de consentimento OAuth, especifique pelo menos seu Endereço de e-mail e o Nome do produto mostrado aos usuários.
    2. Salve as configurações da tela de consentimento e alterne para a guia Credenciais, clicando em Salvar.
    3. Clique em Criar credenciais e em ID do cliente do OAuth para criar um ID do cliente
    4. Clique em Aplicativo da Web, especifique um nome e use https://www.google.com como o URI de redirecionamento.

    5. Clique em Criar para salvar a credencial.

    6. Anote o ID do cliente exibido porque ele será usado em uma etapa posterior para solicitar o token de acesso.

Para mais informações sobre como criar credenciais para a API Admin, consulte Como acessar a API.

Como criar um arquivo de configuração

Crie um arquivo de configuração que defina a implantação do aplicativo Hello World. Em um arquivo chamado app.json, você define o intervalo do Cloud Storage do aplicativo Hello World no campo sourceURL e as informações de configuração da versão, incluindo o ID da versão, no campo id.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Por exemplo, root/python-docs-samples/appengine/standard/hello_world/app.json

Como autorizar solicitações HTTP

Autentique-se com o App Engine para enviar solicitações HTTP com a API Admin.

Use uma das seguintes opções para ajudar você a dar os primeiros passos rapidamente. As opções HTTPS e gcloud fornecem etapas manuais, mas simples, para conseguir tokens de acesso com o objetivo de testar a API Admin.

HTTPS

Para simular um fluxo OAuth 2.0 do lado do cliente, adicione sua credencial de ID do cliente OAuth a um URI e, em seguida, envie a solicitação HTTPS por meio do navegador da Web:

  1. No navegador da Web, solicite um token de acesso usando o ID do cliente de suas credenciais da API. O exemplo a seguir usa client_id=[MY_CLIENT_ID] e redirect_uri=https://www.google.com, em que [MY_CLIENT_ID] é o ID do cliente da credencial que você criou anteriormente:

    https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
    
  2. Recupere o token de acesso da resposta da solicitação.

    O campo de endereço no navegador da Web deve conter o URI de redirecionamento especificado nas suas credenciais junto com o token de acesso anexado ao URI, por exemplo:

    https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
    

    Use o token de acesso [MY_ACCESS_TOKEN] fornecido no campo access_token para enviar solicitações HTTP ao projeto do GCP.

gcloud

Para simplesmente recuperar um token de acesso, execute os seguintes comandos da gcloud:

  1. Defina a credencial do Application Default Credentials (ADC) que você quer usar para solicitar um token de acesso.

    gcloud auth application-default login
    
  2. Solicite o token de acesso:

    gcloud auth application-default print-access-token
    

Para mais detalhes sobre esses comandos, consulte gcloud auth application-default.

Lembre-se: seu token de acesso expira em aproximadamente 60 minutos após a emissão.

As opções acima não se destinam a uso em sua implementação programática, mas as informações sobre como implementar um fluxo de autorização do OAuth 2.0 estão disponíveis em Como acessar a API Admin.

Como implantar o aplicativo Hello World

Use uma solicitação HTTP para implantar o aplicativo Hello World com a API Admin:

  1. Envie uma solicitação POST HTTP usando a API Admin para implantar uma versão do aplicativo Hello World no seu aplicativo do App Engine. Por exemplo:

    POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json
    

    Exemplo de comando cURL:

    Execute o comando no diretório em que você criou o arquivo de configuração app.json, por exemplo:

    cd root/python-docs-samples/appengine/standard/hello_world/
    
    curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions
    

    Em que:

    • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
    • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

    Exemplo de resposta:

    {
      "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
      "metadata": {
        "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
        "insertTime": "2016-07-29T17:12:44.679Z",
        "method": "google.appengine.v1.Versions.CreateVersion",
        "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "user": "me@example.com"
      }
    }
    

    em que [MY_PROJECT_ID] é o ID do seu projeto do GCP.

  2. Verifique se a versão do aplicativo Hello World foi implantada com sucesso no aplicativo do App Engine:

    1. Veja o status da operação de implantação real usando o nome da operação retornado na etapa anterior como o campo name em um método GET HTTP. Por exemplo:

      GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Exemplo de comando cURL:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Em que:

      • [OPERATION_NAME] é o valor do campo name retornado na etapa anterior em que você implantou o aplicativo, por exemplo, apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85;
      • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP;
      • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

      Exemplo de resposta:

      {
        "done": true,
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "endTime": "2016-07-29T17:13:20.424Z",
          "insertTime": "2016-07-29T17:12:44.679Z",
          "method": "google.appengine.v1.Versions.CreateVersion",
          "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "user": "me@example.com"
        },
        "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
        "response": {
          "@type": "type.googleapis.com/google.appengine.v1.Version",
          "creationTime": "2016-07-29T17:12:46.000Z",
          "deployer": "me@example.com",
          "id": "appengine-helloworld",
          "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "runtime": "python27",
          "servingStatus": "SERVING",
          "threadsafe": true,
        }
      }
      

      Em que [MY_PROJECT_ID] é o ID do seu projeto do GCP.

    2. Verifique se a versão do aplicativo Hello World foi criada no seu aplicativo do App Engine usando uma solicitação GET HTTP para visualizar os detalhes da versão. Por exemplo:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      Exemplo de comando cURL:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      em que:

      • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
      • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

      Exemplo de resposta:

      {
        "creationTime": "2016-07-29T17:12:46.000Z",
        "deployer": "me@example.com",
        "deployment": {
          "files": {
            "main.py": {
              "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
              "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
            }
          }
        },
        "handlers": [
          {
            "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
            "login": "LOGIN_OPTIONAL",
            "script": {
              "scriptPath": "main.app",
            },
            "securityLevel": "SECURE_OPTIONAL",
            "urlRegex": "/.*"
          }
        ]
        "id": "appengine-helloworld",
        "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "runtime": "python27",
        "servingStatus": "SERVING",
        "threadsafe": true,
        "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].appspot.com"
      }
      

      em que [MY_PROJECT_ID] é o ID do seu projeto do GCP.

  3. Visualize o aplicativo Hello World em seu navegador da Web acessando o URL especificado no campo versionUrl da resposta HTTP da etapa anterior. Por exemplo:

    https://appengine-helloworld-dot-[MY_PROJECT_ID].appspot.com
    

    em que [MY_PROJECT_ID] é o ID do seu projeto do GCP.

  4. Configure o tráfego para o aplicativo Hello World.

    Por padrão, a versão inicial que você implanta em um novo aplicativo do App Engine recebe automaticamente 100% do tráfego e as versões subsequentes recebem tráfego zero.

    1. Para ver se a versão está configurada para receber tráfego, envie uma solicitação GET HTTP. Por exemplo:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      Exemplo de comando cURL:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      em que:

      • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
      • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

      Exemplo de resposta:

      {
        "name": "apps/[MY_PROJECT_ID]/services/default/",
        "id": "default",
        "split": {
          "allocations": {
            "appengine-helloworld": 1
          }
        }
      }
      

      em que [MY_PROJECT_ID] é o ID do seu projeto do GCP.

    2. Para mover todo o tráfego para uma determinada versão, envie uma solicitação PATCH HTTP. Por exemplo:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }
      

      Exemplo de comando cURL:

      curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
      

      em que:

      • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
      • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

      Exemplo de resposta:

      {
        "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "insertTime": "2016-07-29T17:25:30.413Z",
          "method": "com.google.appengine.v1.Services.UpdateService",
          "target": "apps/[MY_PROJECT_ID]/services/default",
          "user": "me@example.com"
        }
      }
      

      [MY_PROJECT_ID] é o código do seu projeto do GCP.

Aprendizado estendido

Se você tiver mais de uma versão de um aplicativo, poderá executar as etapas a seguir para dividir o tráfego entre essas versões:

  1. Para implantar uma segunda versão do aplicativo Hello World no mesmo aplicativo do App Engine:

    1. No arquivo de configuração app.json existente do aplicativo Hello World que você criou anteriormente, atualize o campo id para especificar uma versão diferente. Por exemplo, anexe um -2:

      "id": "appengine-helloworld-2"
      
    2. Execute novamente as mesmas etapas para implantar uma versão appengine-helloworld-2. Por exemplo:

      1. Faça sua autenticação no projeto.
      2. Implante a nova versão do appengine-helloworld-2.
      3. Verifique se a versão do appengine-helloworld-2 foi implementada com sucesso.
      4. Veja seu app no navegador da Web:
  2. Para dividir o tráfego, siga as instruções em Como migrar e dividir o tráfego. Por exemplo, envie uma solicitação PATCH HTTP:

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }
    

    Exemplo de comando cURL:

    curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
    

    em que:

    • [MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
    • [MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Próximas etapas