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

Cykliczne listy odbiorców są generowane codziennie, gdy zmienia się przynależność do list odbiorców, dzięki czemu zawsze pracujesz z najnowszymi danymi.

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

Codziennie twórz nową listę odbiorców.

Przetwarzanie danych o odbiorcach z jednego dnia i aktualizowanie członkostwa może zająć różną ilość czasu. Nie ma możliwości sprawdzenia, czy dane na liście odbiorców zostały zaktualizowane w ciągu 24 godzin.

Jeśli na przykład codziennie o tej samej porze wysyłasz prośbę o listę odbiorców, w niektóre dni lista odbiorców będzie taka sama jak poprzedniego dnia, a w inne dni będzie się różnić i będzie zawierać dodatkowy dzień zmian członkostwa.

Codzienne tworzenie nowej listy odbiorców

Listy odbiorców są tworzone na podstawie danych zdarzeń z dnia poprzedzającego ostatnie zmiany członkostwa. Jeśli utworzysz listę odbiorców przed codzienną aktualizacją członkostwa, będzie ona używać danych z poprzednich 2 dni. Jeśli utworzysz listę odbiorców po codziennych aktualizacjach członkostwa, będzie ona używać danych z poprzedniego dnia.

Okresowe odpytywanie cyklicznej listy odbiorców

Cykliczne listy odbiorców generują listy odbiorców tylko wtedy, gdy dostępne są dane z dodatkowego dnia. Dzięki temu nie musisz się zastanawiać, kiedy utworzyć nowe listy odbiorców. Zamiast tego możesz przez cały dzień tanio odpytywać cykliczną listę odbiorców, aby sprawdzić, czy są dostępne dodatkowe dane.

okresowe odpytywanie cyklicznej listy odbiorców w ciągu dnia,

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 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 list odbiorców. Na liście odbiorców uwzględniane są 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żywać w kolejnych zapytaniach, aby pobierać metadane konfiguracji tej cyklicznej listy odbiorców. Metadane konfiguracji zawierają też nazwy zasobów instancji list 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

Aby pobrać metadane konfiguracji dotyczące konkretnej cyklicznej listy odbiorców, użyj metody recurringAudienceLists.get. Metadane konfiguracji zawierają nazwy zasobów instancji list odbiorców utworzonych 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 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ć metody recurringAudienceLists.list, aby wyświetlić listę wszystkich cyklicznych list odbiorców w usłudze.

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

Zamiast okresowo sprawdzać metadane konfiguracji dotyczące konkretnej cyklicznej listy odbiorców za pomocą metody recurringAudienceLists.get, możesz asynchronicznie otrzymywać powiadomienia z webhooka, 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 Async audience lists with webhooks.

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

Aby pobrać użytkowników w ramach eksportu listy odbiorców, wywołaj metodę audienceExports.query i podaj nazwę eksportu listy 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 na liście 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
}