Admin API でトラフィックの移行と分割を行う

トラフィックを移行または分割することにより、アプリケーションのバージョンが受信するトラフィックの量を管理します。

トラフィック移行を行うと、リクエストのルーティングが徐々に切り替わり、トラフィックを現在受信しているバージョンから指定された 1 つ以上のバージョンにトラフィックが段階的に移行されます。

トラフィック分割を行うと、指定したパーセンテージでトラフィックをアプリケーションのバージョンに分散します。トラフィック分割により、トラフィックの 100% を 1 つのバージョンに移行したり、指定した割合のトラフィックを複数のバージョンにルーティングしたりできます。トラフィックを 2 つ以上のバージョンに分割すると、バージョン間で A/B テストを実施して、機能をロールアウトする際のペースを制御できます。

トラフィック分割は、ターゲットとなるバージョンを明示的に指定していない URL に適用されます。たとえば、次の URL は、指定されたサービス内の使用可能なすべてのバージョンをターゲットとしているので、トラフィックが分割されます。

  • [MY_PROJECT_ID].appspot.com - トラフィックを default サービスの複数のバージョンに分散します。
  • [MY_SERVICE].[MY_PROJECT_ID].appspot.com - トラフィックを MY_SERVICE サービスの複数のバージョンに分散します。

詳細については、リクエストのルーティング方法をご覧ください。

GCP Console から手動でトラフィックの移行と分割を行う方法については、トラフィックの移行トラフィックの分割をご覧ください。

始める前に

Admin API によるトラフィック移行の動作は、GCP Console とは異なります。Admin API でトラフィックを移行するには、HTTP リクエストの承認が可能で、バージョンがトラフィック移行の要件を満たしていることが必要です。

トラフィック移行(migrateTraffic=true)の要件:

  • トラフィックを構成するには、ユーザー アカウントに必要な権限が含まれている必要があります。

  • 段階的なトラフィック移行は、App Engine フレキシブル環境でサポートされていません。

  • 段階的なトラフィック移行を行うには、以下が構成されているインスタンス内にターゲット バージョンが配置されている必要があります。

トラフィックの移行または分割

アプリのバージョン間でトラフィックを移行または分割するには:

  1. アクセス トークンの取得など、HTTP リクエストを承認します。

    Admin API へのアクセスを承認するには、API アプリのニーズに応じて、さまざまな OAuth フローを使用できます。詳しくは、API へのアクセスをご覧ください。

  2. apps.services コレクションpatch メソッドを使用して、バージョンの構成を更新することにより、トラフィックの移行またはトラフィック分割を構成します。次の例の HTTP PATCH リクエストは、読みやすくするため意図的にラップしてあります。

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

    HTTP リクエストのパラメータとフィールド:

    • updateMask: 更新する構成内のフィールドを指定します。
    • migrateTraffic=true(オプション): 段階的なトラフィック移行を指定します。

    • split: バージョンに対するトラフィックの構成を定義します。

      • shardBy(オプション): トラフィックの分割に使用するメソッドを定義します。これは、段階的なトラフィック移行(migrateTraffic=true)の場合に必要です。有効な値は COOKIE または IP です。
      • allocations: 1 つ以上のバージョンと、各バージョンに分散するトラフィックのパーセンテージを定義します。トラフィックのバージョンとパーセンテージは、key:value ペアとして指定します。トラフィックのパーセンテージは小数で指定し、合計が 1 になるようにします。例: "allocations": { "v1": 0.8, "v2": 0.2 }

    パラメータおよびフィールドの詳細と完全なリストについては、apps.services コレクションをご覧ください。

    HTTP リクエストの例:

    • すべてのトラフィックを 1 つのバージョンに移行する:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
      
    • すべてのトラフィックを v2 に移行する:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
      
    • トラフィックの 80% をバージョン v1、20% を 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 } } }
      

例: トラフィックを別のバージョンに移行する

この例では、デプロイしたばかりの新しいバージョンにすべてのトラフィックを移行する方法を示します。たとえば、サーバーがエラーを返すのでバグを修正し、新しい v2 バージョンをデプロイしてすべてのトラフィックをリダイレクトするような場合です。

すべてのトラフィックを v1 から v2 に移行するには:

  1. apps.services コレクションGET メソッドを使用して、現在トラフィックの 100% が v1 バージョンに送信されていることを確認します。

    HTTP GET リクエストの例:

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

    cURL コマンドの例:

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

    レスポンスの例:

    {
      "name": "apps/[MY_PROJECT_ID]/services/default",
      "id": "default",
      "split": {
        "allocations": {
          "v1": 1
        }
      }
    }
    
  1. apps.services コレクションPATCH メソッドを使用してトラフィック分割の構成を更新し、すべてのトラフィックが新しいバージョンに移行されるようにします。

    HTTP PATCH リクエストには、両方のバージョンが実行されているアプリケーション内のサービス(たとえば default)を指定する必要があります。トラフィック分割の構成の更新を指定するには、updateMask フィールドに split 値を指定する必要もあります。

    HTTP PATCH リクエストの例:

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

    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
    

    レスポンスの例:

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

    ヒント: 上記の HTTP PATCH リクエストは、トラフィックを直ちに v2 バージョンに移行します。トラフィックが段階的に再ルーティングされるように移行するには、shardBy フィールドで migrateTraffic=true パラメータを指定する必要があります。次に例を示します。

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }
    
  2. 構成の更新が完了していることを確認します。

    1. HTTP GET リクエストを使用して更新オペレーションのステータスを表示します。

      更新を実行しているオペレーションのステータスを表示するには、apps.operations コレクションGET メソッドで、前の手順の HTTP レスポンスで返されたオペレーションの name を使用します。

      HTTP GET リクエストの例:

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

      [OPERATION_NAME] は、前の手順で送信した HTTP PATCH リクエストのレスポンスに含まれる name フィールドの値です。

      前の手順の HTTP レスポンスに以下が含まれているとします。

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

      この場合、次の HTTP リクエストを送信するとオペレーションのステータスが表示されします。

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

      cURL コマンドの例:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
      
    2. オペレーションが完了したら、別の HTTP GET リクエストで、バージョンが存在するサービスの詳細を表示できます。

      HTTP GET リクエストの例:

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

      cURL コマンドの例:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      
  3. (省略可)HTTP DELETE リクエストにより、不具合のある v1 バージョンを App Engine アプリケーションから削除できるようになりました。

    HTTP DELETE リクエストの例:

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

    cURL コマンドの例:

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

    ヒント: HTTP GET リクエストを実行してオペレーションが成功したかどうかを確認できます。たとえば、1 つのリクエストで削除オペレーションの完了を確認し、もう 1 つのリクエストでバージョンの削除を確認します。

例: 複数のバージョンにトラフィックを分割する

この例では、アプリケーションの複数のバージョンへのトラフィックの分割を構成する方法を示します。たとえば、新機能を含むバージョン v2 および v3 を作成したが、それらの機能を徐々にロールアウトするため、各バージョンがトラフィックの 20% のみ受信するようにしたいとします。

  1. v2 および v3 バージョンを App Engine アプリケーションにデプロイした後、HTTP PATCH リクエストで 3 つのバージョンを構成し、v1 にトラフィックの 60%、v2v3 にそれぞれ 20% を分散します。

    HTTP PATCH リクエストの例:

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

    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. オペレーションの完了を確認した後、HTTP GET リクエストを送信して、バージョン間でトラフィックが分散されていることを確認できます。次に例を示します。

    HTTP PATCH リクエストの例:

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

    cURL コマンドの例:

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

    レスポンスの例:

    {
      "name": "apps/[MY_PROJECT_ID]/services/default",
      "id": "default",
      "split": {
        "allocations": {
          "v1": 0.6,
          "v2": 0.2,
          "v3": 0.2
        }
      }
    }
    
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...