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

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

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

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

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

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

チュートリアルのクイックスタート: Cloud Run にサンプルサービスをデプロイするの手順に沿って、Google Cloud を使用してサンプル Webhook アプリケーションを作成できます。

サンプルサービスが 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 メソッドからのレスポンスには、指定された Webhook が 5 秒以内に正常に応答したことを確認する webhookNotification が含まれます。

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

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 エポック時刻をマイクロ秒単位で指定します。このタイムスタンプを使用して、リプレイされた通知を特定できます。

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

最初の 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 本文を確認します。