このページは Cloud Translation API によって翻訳されました。

オーディエンスリストの Webhook 通知を受け取る

このガイドでは、Webhook を使用してオーディエンスエクスポートリクエストのステータスに関する非同期通知を受信する方法について説明します。この機能は、Data API の v1alpha バージョンでのみ使用できます。

Webhook 通知は、Google アナリティクスの Data API の高度な機能です。オーディエンスエクスポート機能の概要については、オーディエンスエクスポートを作成するをご覧ください。

Webhook を使用しない場合は、リクエストが完了したタイミングを判断するために、API を定期的にポーリングする必要があります。

Cloud Run を使用してサンプル Webhook アプリケーションを作成する

Google Cloud を使用してサンプルの Webhook アプリケーションを作成するには、クイックスタート: サンプルサービスを Cloud Run にデプロイするをご覧ください。

サンプルサービスが POST Webhook 通知リクエストをリッスンするには、クイックスタートチュートリアルの index.js ファイルを次のコードに置き換えます。

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

このコードは、POST リクエストとして送信された受信 Webhook 通知ごとに、Webhook 通知の JSON 本文とチャンネルトークンの値を出力し、HTTP コード 200 を返して、オペレーションが成功したことを示します。

Cloud Run のクイックスタートチュートリアルの最後まで進み、gcloud run deploy コマンドを使用して Webhook アプリケーションをデプロイしたら、サービスがデプロイされている URL を保存します。

サービス URL がコンソールに表示されます。次に例を示します。

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

これは、アプリケーションが Google アナリティクスからの Webhook 通知をリッスンするサーバー通知 URI です。

オーディエンスリストを作成し、Webhook 通知を有効にする

Webhook 通知をリクエストするには、webhookNotification オブジェクトに次の値を指定します。

webhook 通知を受信するウェブアドレスを含むサーバー通知 URI。
（省略可）メッセージのなりすましを防ぐ任意の文字列 channelToken。Webhook POST リクエストの X-Goog-Channel-Token HTTP ヘッダーに channelToken を指定します。

Webhook を使用したリクエストの例を次に示します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceLists.create メソッドからのレスポンスには webhookNotification が含まれます。これは、指定された Webhook が 5 秒以内に正常に応答したことを確認します。

レスポンスの例を次に示します。

HTTP レスポンス

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

Webhook が応答しなかった場合や、サービス URL が正しくない場合は、代わりにエラーメッセージが返されます。

次のようなエラーが表示されることがあります。

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Webhook 通知を処理する

Webhook サービスへの POST リクエストの本文には、長時間実行オペレーションリソースの JSON バージョンと sentTimestamp フィールドの両方が含まれます。送信されたタイムスタンプには、リクエストが送信された Unix エポックタイム（マイクロ秒単位）が指定されます。このタイムスタンプを使用して、再生された通知を特定できます。

オーディエンスリストの作成中に、Webhook に 1 つまたは 2 つの POST リクエストが送信されます。

最初の POST リクエストはすぐに送信され、新しく作成されたオーディエンスリストが CREATING ステータスになります。Webhook への最初のリクエストが失敗した場合、audienceLists.create オペレーションはエラーと Webhook の失敗の詳細を返します。
2 番目の POST リクエストは、オーディエンスリストの作成が完了した後に送信されます。オーディエンスリストが ACTIVE または FAILED の状態に達すると、作成は完了します。

以下に、CREATING 状態のオーディエンスリストの最初の通知の例を示します。

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

ACTIVE 状態のオーディエンスリストの 2 番目の通知の例を次に示します。

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

2 つ目の通知は、オーディエンスリストが作成され、audienceLists.query メソッドを使用してクエリを実行する準備ができていることを確認します。

audienceLists.create メソッドを呼び出した後に Webhook をテストするには、サンプルの Cloud Run Webhook アプリケーションのログを検査し、Google アナリティクスから送信されたすべての通知の JSON 本文を確認します。