Cykliczne listy odbiorców

W tym dokumencie opisujemy cykliczne listy odbiorców, które są zaawansowaną funkcją Google Analytics Data API w wersji 1. Wprowadzenie do funkcji eksportowania list odbiorców znajdziesz w przewodniku po podstawach eksportu list odbiorców.

Cykliczne listy odbiorców generują listy odbiorców codziennie w miarę zmiany członkostwa, aby mieć pewność, że korzystasz z najnowszych danych.

Zwykłe (niecykliczne) listy odbiorców to statyczne listy użytkowników, którzy znajdują się na liście odbiorców w momencie jej generowania.

Codziennie twórz nową listę odbiorców

Przetwarzanie danych o odbiorcach z jednego dnia i aktualizowanie liczby członków może zająć różny czas. Nie można upewnić się, że dane listy odbiorców są aktualizowane w ciągu 24 godzin.

Na przykład nawet jeśli codziennie wysyłasz prośbę o opracowanie listy odbiorców o tej samej godzinie, w niektórych dniach będzie ona taka sama jak w poprzednim, a w innych będzie się różnić i będzie zawierać dodatkowy dzień zmian członkostwa.

Codziennie tworzenie nowej listy odbiorców

Listy odbiorców są tworzone na podstawie danych zdarzeń z dnia poprzedzającego najnowsze zmiany w członkostwie. Jeśli utworzysz listę odbiorców przed codziennymi aktualizacjami członkostwa, będzie ona korzystać z danych z dwóch poprzednich dni. Jeśli utworzysz listę odbiorców po codziennej aktualizacji danych o członkostwie, będzie ona korzystać z danych z poprzedniego dnia.

Okresowe ankietowanie na cyklicznej liście odbiorców

Cykliczne listy odbiorców tworzy listy odbiorców tylko wtedy, gdy są dostępne dane z dodatkowego dnia. Dzięki temu nie musisz już zgadywać, kiedy utworzyć nowe listy odbiorców. Zamiast tego możesz przez cały dzień przeprowadzać tańsze ankiety na temat cyklicznej listy odbiorców, by sprawdzić, czy są dostępne dodatkowe dane.

okresowe odpytywanie w ciągu dnia listy odbiorców;

Tworzenie cyklicznej listy odbiorców

Aby utworzyć cykliczną listę odbiorców, wywołaj metodę recurringAudienceLists.create za pomocą obiektu RecurringAudienceList w żądaniu. Wymagane są te parametry:

  • Prawidłowa nazwa listy odbiorców w polu audience w formacie properties/{propertyId}/audiences/{audienceId}. Aby uzyskać tę wartość, możesz użyć metody audiences.list w interfejsie Google Analytics Admin API w wersji 1. Pole Audience.name odpowiedzi audiences.list zawiera nazwę listy odbiorców.
  • Prawidłowa lista wymiarów w polu dimensions. Listę wymiarów obsługiwanych przez tę metodę znajdziesz w dokumentacji schematu eksportu odbiorców. Na liście odbiorców znajdują się tylko dane dotyczące wymiarów wymienionych w tym polu.

Oto przykładowa cykliczna prośba o utworzenie listy odbiorców:

Żądanie HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Odpowiedź metody recurringAudienceLists.create zawiera nazwę z pola name (np. properties/1234567/recurringAudienceLists/123). Można jej używać w kolejnych zapytaniach do pobierania metadanych konfiguracji tej cyklicznej listy odbiorców. Metadane konfiguracji zawierają nazwy zasobów instancji listy odbiorców utworzone na potrzeby tej cyklicznej listy odbiorców.

Odpowiedź HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Metadane konfiguracji ankiety

Za pomocą metody recurringAudienceLists.get możesz pobierać metadane konfiguracji konkretnej cyklicznej listy odbiorców. Metadane konfiguracji zawierają nazwy zasobów instancji listy odbiorców utworzone dla tej cyklicznej listy odbiorców.

Oto przykład:

Żądanie HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

W odpowiedzi zwracana jest instancja RecurringAudienceList. Zawiera on metadane konfiguracji, w tym nazwy zasobów instancji listy odbiorców utworzone na potrzeby tej cyklicznej listy odbiorców.

Odpowiedź HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Aby wyświetlić wszystkie cykliczne listy odbiorców danej usługi, możesz użyć parametru recurringAudienceLists.list.

Używaj webhooków, aby otrzymywać asynchroniczne powiadomienia o nowych listach odbiorców

Zamiast okresowo odpytywać za pomocą metody recurringAudienceLists.get metadane konfiguracji pod kątem określonej cyklicznej listy odbiorców, możesz asynchronicznie otrzymywać powiadomienia webhooka, gdy lista odbiorców stanie się dostępna.

Aby skonfigurować powiadomienia webhooka, podczas tworzenia nowej cyklicznej listy odbiorców podaj pole webhookNotification.

Więcej informacji o korzystaniu z webhooków w interfejsie Google Analytics Data API w wersji 1 znajdziesz w dokumentacji WebhookNotification.

Pobieranie użytkowników z eksportu list odbiorców

Aby pobrać dane użytkowników w ramach eksportu list odbiorców, wywołaj metodę audienceExports.query i podaj nazwę eksportu listy odbiorców pobraną z metadanych konfiguracji dostarczanych przez recurringAudienceLists.get lub recurringAudienceLists.list.

Żądanie HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Gdy eksport listy odbiorców jest gotowy, zwracana jest odpowiedź zawierająca listę użytkowników z danej listy:

Odpowiedź HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}