Otrzymuj powiadomienia webhook dotyczące list odbiorców

Ten przewodnik wyjaśnia, jak korzystać z webhooków do otrzymywania powiadomień asynchronicznych. . Ta funkcja jest dostępna tylko w wersji alfa interfejsu Data API.

Powiadomienia webhooka to zaawansowana funkcja narzędzia Dane Google Analytics API. Wprowadzenie do funkcji eksportowania list odbiorców przeczytaj artykuł o tworzeniu eksportu list odbiorców.

Bez webhooków trzeba będzie okresowo odpytywać interfejs API, aby aby określić, kiedy żądanie zostanie zrealizowane.

Tworzenie przykładowej aplikacji webhooka za pomocą Cloud Run

Możesz utworzyć przykładową aplikację webhooka za pomocą Google Cloud, wykonując te czynności samouczek Szybki start: wdrażanie przykładowej usługi w Cloud Run.

Aby przykładowa usługa mogła nasłuchiwać żądań powiadomień webhooka POST, zastąp plik index.js z krótkiego samouczka następującym kod:

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

Ten kod jest drukowany w przypadku każdego przychodzącego powiadomienia webhooka wysłanego jako żądanie POST. treść JSON powiadomienia webhooka i wartość tokena kanału, zwraca kod HTTP 200, aby wskazać udaną operację.

Po zakończeniu samouczka wprowadzającego do Cloud Run i wdrożeniu aplikacji webhooka za pomocą polecenia gcloud run deploy, zapisz adres URL, pod którym wdrożono usługę.

URL usługi zostanie wyświetlony w konsoli, na przykład:

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

To jest identyfikator URI powiadomienia serwera. z którego aplikacja nasłuchuje powiadomień webhooka Google Analytics

Utwórz listę odbiorców i włącz powiadomienia webhooka

Aby zażądać powiadomień webhooka, określ te wartości w webhookNotification obiekt:

  • Identyfikator URI powiadomień serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhooka.

  • (Opcjonalnie) Dowolny ciąg znaków channelToken aby zapobiec sfałszowaniu wiadomości. Podaj channelToken w nagłówku HTTP X-Goog-Channel-Token funkcji żądania POST webhooka.

Oto przykładowe żądanie przy użyciu 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 element webhookNotification, która potwierdza, że podany webhook odpowiedział w czasie krótszym niż 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 odpowiada lub podasz nieprawidłowy adres URL usługi, pojawi się komunikat o błędzie.

Oto przykładowy błąd, który może wystąpić:

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

Przetwarzaj powiadomienia webhooka

Żądanie POST do usługi webhooka zawiera zarówno wersję JSON zasób długo trwającej operacji i pole sentTimestamp. Sygnatura czasowa wysłania określa czas wysłania żądania (w mikrosekundach), Możesz użyć tej sygnatura czasowa, aby identyfikować ponownie odtwarzane powiadomienia.

Podczas tworzenie listy odbiorców:

  1. Pierwsze żądanie POST jest wysyłane natychmiast, pokazując nowo utworzone lista odbiorców w stanie CREATING. Jeśli pierwsza prośba do webhooka nie działa, operacja audienceLists.create zwraca błąd oraz szczegóły błędu webhooka.
  2. Drugie żądanie POST jest wysyłane po uzupełnieniu listy odbiorców. proces tworzenia. Tworzenie zostanie zakończone, gdy lista odbiorców osiągnie stan ACTIVE lub FAILED.

Oto przykład pierwszego powiadomienia o liście odbiorców. CREATING stan:

  {
    "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. ACTIVE stan:

  {
    "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 gotowe do wykonania zapytania za pomocą audienceLists.query .

Aby przetestować webhooki po wywołaniu metody audienceLists.create, możesz: sprawdź logi przykładowej aplikacji webhook Cloud Run i sprawdź treść każdego pliku JSON wysłane przez Google Analytics.