Cykliczne listy odbiorców

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

Listy odbiorców o charakterze cyklicznym są generowane codziennie w miarę zmian w członkostwie odbiorców, dzięki czemu masz dostęp do najnowszych danych.

Zwykłe (niecykliczne) listy odbiorców to statyczne listy użytkowników, którzy w momencie generowania listy należą do segmentu odbiorców.

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 codziennie o tej samej porze wysyłasz prośbę o listę odbiorców, w niektóre dni będzie ona taka sama jak poprzedniego dnia, a w inne będzie się różnić i zawierać dodatkowy dzień zmian w przynależności do listy.

codzienne tworzenie nowej listy odbiorców,

Listy odbiorców są tworzone na podstawie danych zdarzeń z dnia poprzedzającego ostatnie zmiany w programie. Jeśli utworzysz listę odbiorców przed aktualizacją dziennej liczby członków, będzie ona korzystać z danych z 2 dni poprzedzających. Jeśli utworzysz listę odbiorców po codziennych aktualizacjach członkostwa, będzie ona korzystać z danych z poprzedniego dnia.

Okresowe sprawdzanie listy odbiorców cyklicznych

Listy odbiorców tworzone cyklicznie są generowane tylko wtedy, gdy dostępne są dane z kolejnego dnia. Eliminuje to zgadywanie, kiedy należy tworzyć nowe listy odbiorców. Zamiast tego możesz w ciągu dnia tanio sprawdzać listę odbiorców cyklicznych, aby zobaczyć, czy są dostępne dodatkowe dane.

Okresowe sprawdzanie w ciągu dnia cyklicznej listy odbiorców

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 listy odbiorców w polu audience w formacie properties/{propertyId}/audiences/{audienceId}. Aby uzyskać tę wartość, możesz użyć metody audiences.list interfejsu Google Analytics Admin API w wersji 1. Pole Audience.name w 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. 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 do pobierania metadanych 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"
  ]
}

Metadane konfiguracji ankiety

Użyj metody recurringAudienceLists.get do pobierania metadanych konfiguracji dotyczących konkretnej cyklicznej listy odbiorców. Metadane konfiguracji zawierają nazwy zasobów instancji list 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 zostanie zwrócona instancja RecurringAudienceList. Zawiera 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"
  ]
}

Możesz użyć recurringAudienceLists.list do wyświetlenia wszystkich cyklicznych list odbiorców w usłudze.

Używanie webhooków do otrzymywania asynchronicznych powiadomień o nowych listach odbiorców

Zamiast okresowo odpytywać metadane konfiguracji dotyczące konkretnej cyklicznej listy odbiorców za pomocą metody recurringAudienceLists.get, 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 elementów Webhook w interfejsie Google Analytics Data API w wersji 1 znajdziesz w Async audience lists with webhooks przewodniku.

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

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

Żądanie HTTP

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

Jeśli eksport listy odbiorców jest gotowy, zwracana jest odpowiedź zawierająca listę użytkowników z danej listy 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
}