Comienza a usar la API de Administrador

ID de región

REGION_ID es un código abreviado que Google asigna en función de la región que eliges cuando creas la app. El código no corresponde a un país ni a una provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia que se suelen usar. En el caso de las apps creadas después de febrero de 2020, REGION_ID.r se incluye en las URL de App Engine. En el caso de las apps existentes creadas antes de esta fecha, el ID de región es opcional en la URL.

Obtén más información acerca de los ID de región.

Esta guía está diseñada para ayudarte a aprender a usar la API de App Engine Admin a fin de implementar una aplicación de muestra de Python en App Engine. Puedes usar el proceso general a fin de obtener información para crear un código que administre e implemente tus apps de manera programática.

En esta guía, la muestra que se usa es una app de Hello World simple que muestra el texto “Hello, World!”. y está disponible en GitHub. Para la autorización con la consola de Google Cloud, se usa un ID de cliente de OAuth y un navegador web. Para demostrar los pasos individuales del proceso, se proporcionan comandos cURL a fin de que puedas enviar solicitudes HTTP desde tu terminal.

Objetivos

  • Habilita las API en tu proyecto de la consola de Google Cloud y crea credenciales de ID de cliente de OAuth.
  • Obtén tokens de acceso para autenticar con App Engine.
  • Usa la API de Administrador para implementar la app de muestra en App Engine.
  • Configura el tráfico para la versión en la que implementaste la app de muestra (opcional).

Antes de comenzar

Configura tu proyecto de Google Cloud

Habilita la API de App Engine Admin y las API de Cloud Storage en tu proyecto de Google Cloud y, luego, configura las credenciales:

  1. Habilita las API en la consola de Google Cloud:

    Habilitar las API

  2. En el asistente, selecciona un proyecto existente de la lista o haz clic en Continuar para crear un proyecto nuevo.

  3. Haz clic en Continuar para crear una credencial de ID de cliente de OAuth:

    1. En la pantalla de consentimiento de OAuth, especifica al menos tu dirección de correo electrónico y el nombre del producto que se muestra a los usuarios.
    2. Guarda la configuración de la pantalla de consentimiento y, luego, haz clic en Guardar para guardar la pestaña Credenciales.
    3. Haz clic en Crear credenciales y, luego, en ID de cliente de OAuth para crear un ID de cliente.
    4. Haz clic en Aplicación web, especifica un nombre y, luego, usa https://www.google.com como el URI de redireccionamiento.

    5. Haz clic en Crear para guardar la credencial.

    6. Toma nota del ID de cliente que se muestra porque se usará en un paso posterior para solicitar tu token de acceso.

Si deseas obtener más información a fin de crear credenciales para la API de Administrador, consulta Accede a la API.

Crea un archivo de configuración

Crea un archivo de configuración que defina la implementación de la app de Hello World. En un archivo llamado app.json, define el bucket de Cloud Storage de la app de Hello World en el campo sourceUrl y la información de configuración de la versión, incluido el ID de la versión en el 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 ejemplo, root/python-docs-samples/appengine/standard/hello_world/app.json

Autoriza solicitudes HTTP

Autentica con App Engine para poder enviar solicitudes HTTP con la API de Administrador.

Usa cualquiera de las siguientes opciones para comenzar de inmediato. Las opciones HTTPS y gcloud te proporcionan pasos manuales, pero simples, para obtener tokens de acceso con el fin de probar la API de administrador.

HTTPS

Para simular un flujo de OAuth 2.0 del lado del cliente, agrega la credencial de ID de cliente de OAuth a un URI y, luego, envía la solicitud HTTPS a través de tu navegador web:

  1. En tu navegador web, solicita un token de acceso mediante el ID de cliente de tus credenciales de la API. En el siguiente ejemplo, se usan client_id=[MY_CLIENT_ID] y redirect_uri=https://www.google.com, en los que [MY_CLIENT_ID] es el ID de cliente de la credencial que creaste antes:

    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. Recupera el token de acceso de la respuesta de la solicitud.

    El campo de dirección de tu navegador web debe contener el URI de redireccionamiento especificado en tus credenciales junto con el token de acceso anexado al URI, por ejemplo:

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

    Ahora puedes usar el token de acceso [MY_ACCESS_TOKEN] que se proporciona en el campo access_token para enviar solicitudes HTTP a tu proyecto de Google Cloud.

gcloud

Para recuperar un token de acceso, ejecuta los siguientes comandos de gcloud:

  1. Configura la credencial predeterminada de la aplicación (ADC) que deseas usar para solicitar un token de acceso:

    gcloud auth application-default login
    
  2. Solicita el token de acceso:

    gcloud auth application-default print-access-token
    

Para obtener detalles sobre estos comandos, consulta gcloud auth application-default.

Recuerda: Tu token de acceso vencerá unos 60 minutos después de su emisión.

Las opciones anteriores no están diseñadas con el fin de usarse en tu implementación programática, pero puedes obtener información para implementar un flujo de autorización de OAuth 2.0 en Accede a la API de Administrador.

Implementa la app de Hello World

Usa una solicitud HTTP para implementar la app de Hello World con la API de Administrador:

  1. Envía una solicitud HTTP POST mediante la API de Administrador para implementar una versión de la app de Hello World en tu aplicación de App Engine, por ejemplo:

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

    A continuación, se muestra un ejemplo del comando cURL:

    Ejecuta el comando desde el directorio en el que creaste el archivo de configuración app.json, por ejemplo:

    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
    

    Aquí:

    • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
    • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

    Respuesta de ejemplo:

    {
      "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"
      }
    }
    

    En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

  2. Verifica si la versión de la app de Hello World se implementó de forma correcta en tu aplicación de App Engine:

    1. Consulta el estado de la operación de implementación real con el nombre de la operación que se mostró en el paso anterior como el campo name en un método GET HTTP, por ejemplo:

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

      A continuación, se muestra un ejemplo del comando cURL:

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

      Aquí:

      • [OPERATION_NAME] es el valor del campo name que se mostró en el paso anterior cuando implementaste la app, por ejemplo, apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
      • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
      • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

      Respuesta de ejemplo:

      {
        "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,
        }
      }
      

      En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

    2. Verifica que la versión de la app de Hello World se creó en la aplicación de App Engine mediante una solicitud GET HTTP para ver los detalles de la versión, como se muestra a continuación:

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

      A continuación, se muestra un ejemplo del 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
      

      Aquí:

      • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
      • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

      Respuesta de ejemplo:

      {
        "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].[REGION_ID].r.appspot"
      }
      

      En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

  3. Para ver la app de Hello World en tu navegador web, visita la URL especificada en el campo versionUrl de la respuesta HTTP del paso anterior, por ejemplo:

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

    En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

    REGION_ID es un código abreviado que Google asigna en función de la región que seleccionas cuando creas la app. El código no corresponde a un país ni a una provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia que se suelen usar. En el caso de las apps creadas después de febrero de 2020, REGION_ID.r se incluye en las URL de App Engine. En el caso de las apps existentes creadas antes de esta fecha, el ID de región es opcional en la URL.

  4. Configura el tráfico para la app de Hello World.

    De forma predeterminada, la versión inicial que implementas en una aplicación nueva de App Engine recibe de manera automática el 100% del tráfico, y las versiones posteriores no reciben tráfico.

    1. Para ver si la versión está configurada a fin de recibir tráfico, envía una solicitud HTTP GET, por ejemplo:

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

      A continuación, se muestra un ejemplo del comando cURL:

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

      Aquí:

      • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
      • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

      Respuesta de ejemplo:

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

      En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

    2. Para mover todo el tráfico a una versión, envía una solicitud HTTP PATCH, por ejemplo:

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

      A continuación, se muestra un ejemplo del 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
      

      Aquí:

      • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
      • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

      Respuesta de ejemplo:

      {
        "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"
        }
      }
      

      En el ejemplo anterior, [MY_PROJECT_ID] es el ID del proyecto de Google Cloud.

Aprendizaje extendido

Si tienes más de una versión de una app, puedes realizar los siguientes pasos para dividir el tráfico entre esas versiones:

  1. Para implementar una segunda versión de la app de Hello World en la misma aplicación de App Engine, haz lo siguiente:

    1. En el archivo de configuración app.json existente de la app de Hello World que creaste antes, actualiza el campo id para especificar una versión diferente. Por ejemplo, agrega un -2:

      "id": "appengine-helloworld-2"
      
    2. Vuelve a realizar los mismos pasos para implementar una versión appengine-helloworld-2, por ejemplo:

      1. Autentica con tu proyecto.
      2. Implementa la versión nueva appengine-helloworld-2
      3. Verifica que la versión appengine-helloworld-2 se haya implementado de forma correcta.
      4. Visualiza la app en el navegador web
  2. Sigue las instrucciones para dividir el tráfico en Migra y divide tráfico, por ejemplo, envía una solicitud HTTP PATCH:

    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' } } }
    

    A continuación, se muestra un ejemplo del 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
    

    Aquí:

    • [MY_ACCESS_TOKEN] es el token de acceso que obtuviste para autorizar las solicitudes HTTP.
    • [MY_PROJECT_ID] es el ID del proyecto en el que deseas implementar la versión.

¿Qué sigue?

  • Crea, configura y configura las credenciales de tus aplicaciones: Accede a la API