Migra y divide el tráfico con 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.

Administra cuánto tráfico que recibe una versión de la aplicación mediante la migración o división de tráfico.

La migración de tráfico cambia el enrutamiento de solicitudes sin problemas y migra el tráfico de forma gradual desde versiones que reciben el tráfico a una o más versiones que especifiques.

La división del tráfico distribuye un porcentaje de este a las versiones de tu aplicación. Puedes dividir el tráfico para trasladar el 100% del tráfico a una sola versión o a fin de enrutar los porcentajes de tráfico a varias versiones. Dividir el tráfico a dos o más versiones te permite realizar pruebas A/B entre las versiones y controlar el ritmo cuando implementas características.

Recuerda: La división del tráfico se aplica a las URL que no se orientan especialmente a una versión. Por ejemplo, las siguientes URL dividen el tráfico porque se orientan a todas las versiones disponibles dentro del servicio especificado:

  • [MY_PROJECT_ID].[REGION_ID].r.appspot.com: Distribuye tráfico a versiones del servicio default.
  • [MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com: Distribuye tráfico a versiones del servicio MY_SERVICE.

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.

Para obtener más información, consulta Cómo se enrutan las solicitudes.

Para realizar una migración y división del tráfico de forma manual desde la consola de Google Cloud, consulta Migra el tráfico y Divide el tráfico.

Antes de comenzar

La migración del tráfico con la API de Administrador se comporta diferente a la de la consola de Google Cloud. Para migrar el tráfico con la API de Administrador, debes poder autorizar tus solicitudes HTTP y las versiones deben cumplir con los requisitos de migración de tráfico:

Requisitos para la migración de tráfico (migrateTraffic=true):

Migra o divide el tráfico

Para migrar o dividir el tráfico entre las distintas versiones de tu aplicación, haz lo siguiente:

  1. Autoriza tus solicitudes HTTP, por ejemplo, obtén un token de acceso.

    La autorización de acceso a la API de Administrador se puede realizar con diferentes flujos de OAuth según las necesidades de tu app de API. Para obtener más información, consulta Accede a la API.

  2. Usa el método patch de la colección apps.services a fin de actualizar la configuración de la versión para migrar el tráfico o configurar su división. La siguiente solicitud HTTP de muestra PATCH se unió de forma intencional para facilitar la lectura:

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/
      ?updateMask=split {
        "split": {
          "shardBy": "[MY_SHARDBY_METHOD]",
          "allocations": { "[MY_APP_VERSION]": [MY_TRAFFIC_PERCENT] }
        }
      }
    

    Parámetros de solicitud HTTP y campos:

    • updateMask: Especifica cuál de los campos de la configuración se actualizará.
    • migrateTraffic=true: Especifica migrar el tráfico de manera gradual (opcional).

    • split: Define la configuración del tráfico a tus versiones.

      • shardBy: Define el método que se usará para dividir el tráfico (opcional). Obligatorio para la migración gradual del tráfico (migrateTraffic=true). Los valores válidos son COOKIE o IP.
      • allocations: Define una o más versiones y el porcentaje de tráfico que se distribuye a cada versión. La versión y el porcentaje de tráfico se especifican como un par key:value. El porcentaje de tráfico se especifica como una fracción decimal y debe sumar 1. Ejemplo: "allocations": { "v1": 0.8, "v2": 0.2 }

    Consulta la colección apps.services para obtener detalles y la lista completa de parámetros y campos.

    A continuación, se muestran ejemplos de solicitudes HTTP:

    • Mueve todo el tráfico a una versión:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
      
    • Migra todo el tráfico a v2:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
      
    • Divide el 80% del tráfico a la versión v1 y el 20% a v2:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": 0.8, "v2": 0.2 } } }
      

Ejemplo: Migra el tráfico a otra versión

En este ejemplo, se muestra cómo mover todo el tráfico a una versión nueva que acabas de implementar. Por ejemplo, el servidor muestra errores, de modo que corregiste el error, implementaste la versión v2 nueva y ahora quieres redireccionar todo el tráfico.

Para mover todo el tráfico de v1 a v2, haz lo siguiente:

  1. Verifica que el 100% del tráfico se envíe a la versión v1 con el método GET de la colección apps.services.

    A continuación, se muestra un ejemplo de una solicitud GET HTTP:

    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
    

    Respuesta de ejemplo:

    {
      "name": "apps/[MY_PROJECT_ID]/services/default",
      "id": "default",
      "split": {
        "allocations": {
          "v1": 1
        }
      }
    }
    
  1. Actualiza la configuración de la división de tráfico para que todo el tráfico se transfiera a la versión nueva mediante el método PATCH de la colección apps.services.

    En la solicitud HTTP PATCH, debes especificar el servicio dentro de la aplicación en el que se ejecutan ambas versiones, por ejemplo, default. También debes incluir el campo updateMask con el valor split para especificar que actualizas la configuración de la división de tráfico.

    A continuación, se muestra un ejemplo de una solicitud PATCH HTTP:

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

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

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

    Respuesta de ejemplo:

    {
      "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
      "metadata": {
        "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
        "insertTime": "2015-05-29T17:25:30.413Z",
        "method": "com.google.appengine.v1.Services.UpdateService",
        "target": "apps/[MY_PROJECT_ID]/services/default",
        "user": "me@example.com"
      }
    }
    
    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }
    
  2. Asegúrate de que se haya completado la actualización de configuración:

    1. Visualiza el estado de la operación de actualización con una solicitud HTTP GET:

      Para ver el estado de la operación que ejecuta la actualización, usa el método GET de la colección apps.operations junto con la operación name que se mostró en la respuesta HTTP del paso anterior:

      A continuación, se muestra un ejemplo de una solicitud GET HTTP:

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

      En el ejemplo anterior, [OPERATION_NAME] es el valor del campo name en la respuesta de la solicitud HTTP PATCH que enviaste en el paso anterior.

      Si la respuesta HTTP del paso anterior incluye lo siguiente:

      "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
      

      Luego, envías la solicitud HTTP siguiente para ver el estado de la operación:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
      

      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]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
      
    2. Una vez completada la operación, puedes ver los detalles del servicio en el que la versión está con otra solicitud HTTP GET:

      A continuación, se muestra un ejemplo de una solicitud GET HTTP:

      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
      
  3. Opcional: Ahora puedes quitar la versión con errores v1 de tu aplicación de App Engine con una solicitud DELETE HTTP.

    A continuación, se muestra un ejemplo de una solicitud DELETE HTTP:

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

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

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

Ejemplo: Divide el tráfico entre versiones

En este ejemplo, se muestra cómo configurar la división del tráfico en varias versiones de tu aplicación. Por ejemplo, acabas de crear la versión v2 y v3, que incluyen características nuevas, pero deseas implementarlas de forma lenta para que cada una reciba solo el 20% del tráfico.

  1. Después de implementar las versiones v2 yv3 de tu aplicación de App Engine, debes usar la solicitud HTTP PATCH a fin de configurar las tres versiones para que el tráfico se divida en un 60% a v1 y un 20% cada uno de v2 y v3:

    A continuación, se muestra un ejemplo de una solicitud PATCH HTTP:

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": "0.6", "v2": "0.2", "v3": "0.2" } } }
    

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

    curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'v1': '0.6', 'v2': '0.2', 'v3': '0.2' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
    
  2. Después de verificar que la operación se haya completado, puedes enviar la solicitud HTTP GET para verificar que el tráfico se haya dividido en tus versiones, por ejemplo:

    A continuación, se muestra un ejemplo de una solicitud PATCH HTTP:

    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
    

    Respuesta de ejemplo:

    {
      "name": "apps/[MY_PROJECT_ID]/services/default",
      "id": "default",
      "split": {
        "allocations": {
          "v1": 0.6,
          "v2": 0.2,
          "v3": 0.2
        }
      }
    }