Cykliczne listy odbiorców

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

Cykliczne listy odbiorców są generowane codziennie w miarę zmian w członkostwie odbiorców, dzięki czemu zawsze pracujesz z najnowszymi danymi.

Zwykłe (niecykliczne) listy odbiorców to statyczne listy użytkowników w grupie odbiorców w momencie wygenerowania listy.

Codzienne tworzenie nowej listy odbiorców

Przetwarzanie danych o odbiorcach z jednego dnia i aktualizowanie członkostwa zajmuje różny czas. Nie ma pewności, że dane na liście odbiorców zostaną zaktualizowane w ciągu 24 godzin.

Na przykład nawet jeśli będziesz wysyłać prośbę o listę odbiorców o tej samej porze każdego dnia, w niektóre dni lista odbiorców będzie taka sama jak poprzedniego dnia, a w inne dni będzie inna i będzie zawierać dodatkowy dzień zmian w członkostwie.

Listy odbiorców są oparte na danych o zdarzeniach z dnia poprzedzającego najnowsze zmiany w członkostwie. Jeśli utworzysz listę odbiorców przed codziennymi aktualizacjami członkostwa, będzie ona zawierać dane z 2 dni. Jeśli utworzysz listę odbiorców po codziennych aktualizacjach członkostwa, będzie ona zawierać dane z poprzedniego dnia.

Okresowe sprawdzanie cyklicznej listy odbiorców

Cykliczne listy odbiorców są generowane tylko wtedy, gdy dostępne są dane z dodatkowego dnia. Eliminuje to konieczność zgadywania, kiedy utworzyć nowe listy odbiorców. Zamiast tego możesz tanio sprawdzać cykliczną listę odbiorców przez cały dzień, aby sprawdzić, czy są dostępne dodatkowe dane.

Tworzenie cyklicznej listy odbiorców

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

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

Oto przykładowe żądanie utworzenia cyklicznej 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ę w polu name (np. properties/1234567/recurringAudienceLists/123), której można użyć w kolejnych zapytaniach, aby pobrać metadane konfiguracji tej cyklicznej listy odbiorców. Metadane konfiguracji zawierają też nazwy zasobów instancji listy odbiorców utworzonych 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"
  ]
}

Sprawdzanie metadanych konfiguracji

Aby pobrać metadane konfiguracji dotyczące konkretnej cyklicznej listy odbiorców, użyj recurringAudienceLists.get metody. Metadane konfiguracji zawierają nazwy zasobów instancji listy odbiorców utworzonych na potrzeby 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 ona metadane konfiguracji, w tym nazwy zasobów instancji listy odbiorców utworzonych 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ć listę wszystkich cyklicznych list odbiorców w usłudze, możesz użyć metody recurringAudienceLists.list.

Otrzymywanie asynchronicznych powiadomień o nowych listach odbiorców za pomocą webhooków

Zamiast okresowo sprawdzać metadane konfiguracji dotyczące konkretnej cyklicznej listy odbiorców za pomocą recurringAudienceLists.get metody, możesz asynchronicznie otrzymywać powiadomienia webhook, gdy lista odbiorców stanie się dostępna.

Aby skonfigurować powiadomienia webhook, podczas tworzenia nowej cyklicznej listy odbiorców określ pole webhookNotification.

Więcej informacji o korzystaniu z webhooków w interfejsie Google Analytics Data API w wersji 1 znajdziesz w przewodniku Async audience lists with webhooks.

Pobieranie użytkowników w eksporcie list odbiorców

Aby pobrać użytkowników w eksporcie list odbiorców, wywołaj metodę audienceExports.query i określ nazwę eksportu list odbiorców pobraną z metadanych konfiguracji udostępnionych przez recurringAudienceLists.get lub recurringAudienceLists.list.

Żądanie HTTP

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

Jeśli eksport list odbiorców jest gotowy, zwracana jest odpowiedź zawierająca listę użytkowników w grupie odbiorców:

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
}