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 eksportowania list odbiorców znajdziesz w podstawowym przewodniku po eksportowaniu list odbiorców.

Listy odbiorców o charakterze cyklicznym są generowane codziennie w miarę zmian w członkostwie odbiorców, aby zapewnić Ci dostęp do najnowszych danych.

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

Codzienne tworzenie nowej listy odbiorców

Przetworzenie danych o odbiorcach z jednego dnia i zaktualizowanie członkostwa zajmuje różną ilość czasu. 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 o zdarzeniach z dnia poprzedzającego ostatnie zmiany w członkostwie. Jeśli utworzysz listę odbiorców przed codziennymi aktualizacjami członkostwa, 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 cyklicznej listy odbiorców

Listy odbiorców tworzone cyklicznie są generowane tylko wtedy, gdy dostępne są dane z kolejnego dnia. Dzięki temu nie musisz zgadywać, kiedy utworzyć nowe listy odbiorców. Zamiast tego możesz w ciągu dnia tanio odpytywać listę odbiorców cyklicznych, aby sprawdzić, czy są dostępne dodatkowe dane.

Okresowe sprawdzanie w ciągu dnia powtarzającej się 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 poluaudience 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ę 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 przypadku usługi.

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 eksportowanie listy odbiorców jest gotowe, zwracana jest odpowiedź zawierająca listę użytkowników z tej 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
}