オーディエンス リストの 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 メソッドからのレスポンスには、指定した 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 エポック時間（マイクロ秒単位）を指定します。このタイムスタンプを使用して、再生された通知を識別できます。

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

  1. 最初の POST リクエストはすぐに送信され、新しく作成されたオーディエンス リストが CREATING 状態になります。Webhook への最初のリクエストが失敗すると、audienceLists.create オペレーションはエラーと Webhook の失敗の詳細を返します。
  2. 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 本文を確認します。