Otrzymuj powiadomienia webhook dotyczące list odbiorców

Z tego przewodnika dowiesz się, jak używać webhooków do otrzymywania asynchronicznych powiadomień o stanie żądań eksportu odbiorców. Ta funkcja jest dostępna tylko w wersji alfa 1 interfejsu Data API.

Powiadomienia webhook to zaawansowana funkcja interfejsu Google Analytics Data API. Więcej informacji o funkcji eksportu odbiorców znajdziesz w artykule Tworzenie eksportu odbiorców.

Bez webhooków musisz okresowo wysyłać zapytania do interfejsu API, aby sprawdzić, kiedy żądanie zostanie zrealizowane.

Tworzenie przykładowej aplikacji webhook za pomocą Cloud Run

Możesz utworzyć przykładową aplikację webhook za pomocą Google Cloud, postępując zgodnie z instrukcjami w samouczku Szybki start: wdrażanie przykładowej usługi w Cloud Run.

Aby przykładowa usługa mogła nasłuchiwać żądań powiadomień webhook POST, zastąp plik index.js z samouczka szybkiego startu tym kodem:

  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}`);
  });

W przypadku każdego przychodzącego powiadomienia webhook wysłanego jako żądanie POST ten kod wyświetla treść JSON powiadomienia webhook i wartość tokena kanału oraz zwraca kod HTTP 200, aby wskazać, że operacja się powiodła.

Gdy przejdziesz do końca samouczka szybkiego startu Cloud Run i wdrożysz aplikację webhook za pomocą polecenia gcloud run deploy, zapisz adres URL, pod którym wdrożona jest usługa.

Adres URL usługi jest wyświetlany w konsoli, na przykład:

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

Jest to adres URI powiadomienia serwera pod którym Twoja aplikacja nasłuchuje powiadomień webhook z Google Analytics.

Tworzenie listy odbiorców i włączanie powiadomień webhook

Aby poprosić o powiadomienia webhook, w webhookNotification obiekcie określ te wartości:

  • Adres URI powiadomienia serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhook.

  • (Opcjonalnie) Dowolny ciąg znaków channelToken który chroni przed podszywaniem się pod wiadomość. Określ channelToken w nagłówku HTTP X-Goog-Channel-Token żądania POST webhook.

Oto przykładowe żądanie z użyciem webhooków:

Żądanie 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"
    }
  ]
}

Odpowiedź z metody audienceLists.create zawiera webhookNotification, co potwierdza, że określony webhook odpowiedział w ciągu 5 sekund.

Oto przykładowa odpowiedź:

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

Jeśli webhook nie odpowie lub podasz nieprawidłowy adres URL usługi, zamiast tego zostanie zwrócony komunikat o błędzie.

Oto przykład błędu, który możesz otrzymać:

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

Przetwarzanie powiadomień webhook

Żądanie POST do usługi webhook zawiera w treści zarówno wersję JSON zasobu długo trwającej operacji, jak i pole sentTimestamp. Sygnatura czasowa wysłania określa czas epoki uniksowej w mikrosekundach, w którym wysłano żądanie. Możesz użyć tej sygnatury czasowej, aby zidentyfikować powtórzone powiadomienia.

Podczas tworzenia listy odbiorców do webhooka wysyłane jest jedno lub dwa żądania POST:

  1. Pierwsze żądanie POST jest wysyłane natychmiast i pokazuje nowo utworzoną listę odbiorców w stanie CREATING. Jeśli pierwsze żądanie do webhooka nie powiedzie się, operacja audienceLists.create zwróci błąd i szczegóły niepowodzenia webhooka.
  2. Drugie żądanie POST jest wysyłane po zakończeniu tworzenia listy odbiorców. Tworzenie jest zakończone, gdy lista odbiorców osiągnie stan ACTIVE lub FAILED.

Oto przykład pierwszego powiadomienia o liście odbiorców w stanie 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"
      }
  }

Oto przykład drugiego powiadomienia o liście odbiorców w stanie ACTIVE:

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

Drugie powiadomienie potwierdza, że lista odbiorców została utworzona i jest gotowa do przeszukania za pomocą audienceLists.query metody.

Aby przetestować webhooki po wywołaniu metody audienceLists.create, możesz sprawdzić logi przykładowej aplikacji webhook Cloud Run i zobaczyć treść JSON każdego powiadomienia wysłanego przez Google Analytics.