Eksportowanie danych z Analytics

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Konfigurowanie uprawnień przypisanych agentów usługi

Aby skonfigurować uprawnienia przypisanych agentów obsługi klienta w ramach przygotowań do zmian opisanych powyżej, wykonaj te czynności.

1. Aby znaleźć nazwę agenta usługi Google Cloud, wpisz to polecenie:

   curl -X GET \
     "https://api.enterprise.apigee.com/v1/organizations/ORG" \
     -u email:password \
     | jq -r '.properties.property[] | select(.name=="serviceAgent.analytics") | .value'

   ORG to Twoja organizacja. Zwraca nazwę i wartość agenta usługi, jak pokazano poniżej:

   "property" : [
     {
      "name" : "serviceAgent.analytics",
      "value" : "service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com"
      },

2. Otwórz panel IAM w konsoli Google Cloud.
3. wybrać projekt Google Cloud;
4. U góry panelu Uprawnienia kliknij Dodaj.
5. W polu Nowe podmioty zabezpieczeń wpisz agenta usługi value zwróconego w kroku 1. Na przykład znak value pokazany w kroku 1 to service-9q1ibk@gcp-sa-apigee-uap.iam.gserviceaccount.com.
6. Kliknij przycisk + Dodaj kolejną rolę i dodaj te role:
   • Użytkownik BigQuery
   • Administrator miejsca na dane
7. Kliknij Zapisz.

Dane Apigee Analytics

Format eksportu danych

Eksportuj dane analityczne w jednym z tych formatów:

• Plik CSV

  Domyślnym separatorem jest przecinek (,). Obsługiwane znaki separatora to przecinek (,), pionowa kreska (|) i tabulator (\t). Skonfiguruj wartość za pomocą właściwości csvDelimiter zgodnie z opisem w artykule Dokumentacja właściwości żądania eksportu .

• JSON (rozdzielany znakiem nowej linii)

  Umożliwia użycie znaku nowego wiersza jako separatora.

Wyeksportowane dane obejmują wszystkie dane i wymiary analityczne wbudowane w Edge oraz wszelkie dodane przez Ciebie niestandardowe dane analityczne. Opis eksportowanych danych znajdziesz w artykule Dane, wymiary i filtry Analytics.

Dane analityczne możesz eksportować do tych repozytoriów danych:

• Google Cloud Storage
• Google BigQuery,

Omówienie procesu eksportowania

Poniżej znajdziesz podsumowanie procesu eksportowania danych analitycznych:

1. Skonfiguruj repozytorium danych (Cloud Storage lub BigQuery) na potrzeby eksportowania danych. Musisz się upewnić, że repozytorium danych zostało prawidłowo skonfigurowane, a konto usługi używane do zapisywania danych w repozytorium ma odpowiednie uprawnienia.

2. Utwórz magazyn danych, który określa właściwości repozytorium danych (Cloud Storage lub BigQuery), do którego eksportujesz dane, w tym dane logowania używane do uzyskiwania dostępu do repozytorium danych.

   Gdy tworzysz magazyn danych, przesyłasz do Edge Credentials Vault dane logowania do repozytorium danych, aby je bezpiecznie przechowywać. Mechanizm eksportowania danych używa tych danych logowania do zapisywania danych w repozytorium danych.

3. Użyj interfejsu API do eksportowania danych, aby rozpocząć eksportowanie danych. Eksport danych jest uruchamiany asynchronicznie w tle.

4. Użyj interfejsu Data Export API, aby określić, kiedy eksport się zakończy.

5. Po zakończeniu eksportowania uzyskaj dostęp do wyeksportowanych danych w repozytorium danych.

W sekcjach poniżej znajdziesz szczegółowe informacje o tych krokach.

Konfigurowanie repozytorium danych

Mechanizm eksportowania danych analitycznych zapisuje dane w Cloud Storage lub BigQuery. Aby można było zapisać dane, musisz:

• Utwórz konto usługi Google Cloud Platform.
• Ustaw rolę konta usługi, aby mogło ono uzyskać dostęp do Cloud Storage lub BigQuery.

Tworzenie konta usługi dla Cloud Storage lub BigQuery

Konto usługi to rodzaj konta Google, które należy do Twojej aplikacji, a nie do użytkownika. Aplikacja używa następnie konta usługi, aby uzyskać dostęp do usługi.

Konto usługi ma klucz konta usługi reprezentowany przez ciąg JSON. Podczas tworzenia magazynu danych Edge, który definiuje połączenie z repozytorium danych, przekazujesz ten klucz. Mechanizm eksportowania danych używa następnie klucza do uzyskiwania dostępu do repozytorium danych.

Konto usługi powiązane z kluczem musi być właścicielem projektu Google Cloud Platform i mieć uprawnienia do zapisu w zasobniku Google Cloud Storage. Informacje o tworzeniu kluczyka serwisowego i pobieraniu wymaganego ładunku znajdziesz w dokumentacji Google Cloud Platform w artykule Tworzenie kluczy kont usługi i zarządzanie nimi (w języku angielskim).

Na przykład po pierwszym pobraniu klucza będzie on sformatowany jako obiekt JSON:

{ 
  "type": "service_account", 
  "project_id": "myProject", 
  "private_key_id": "12312312", 
  "private_key": "-----BEGIN PRIVATE KEY-----\n...", 
  "client_email": "client_email@developer.gserviceaccount.com", 
  "client_id": "879876769876", 
  "auth_uri": "https://accounts.google.com/organizations/oauth2/auth", 
  "token_uri": "https://oauth2.googleapis.com/token", 
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2", 
  "client_x509_cert_url": "https://www.googleapis.com" 
}

Konfigurowanie Google Cloud Storage

Zanim wyeksportujesz dane do Google Cloud Storage:

• Upewnij się, że interfejsy BigQuery i Cloud Resource Manager są włączone w projekcie Google Cloud Platform. Instrukcje znajdziesz w artykule Włączanie interfejsów API. Apigee korzysta z interfejsu BigQuery API, aby wykorzystywać funkcje eksportowania BigQuery podczas eksportowania do Cloud Storage, oraz z interfejsu Cloud Resource Manager API, aby sprawdzać uprawnienia przed każdym eksportem.

• Sprawdź, czy do konta usługi są przypisane te role:

  • Użytkownik zadań BigQuery
  • Tworzący obiekty Cloud Storage
  • Administrator pamięci masowej (wymagany tylko w przypadku testowania magazynu danych zgodnie z opisem w artykule Testowanie konfiguracji magazynu danych). Jeśli ta rola jest zbyt ogólna, możesz zamiast niej dodać uprawnienie storage.buckets.get do istniejącej roli).

  Jeśli chcesz zmodyfikować istniejącą rolę lub utworzyć rolę niestandardową, dodaj do niej te uprawnienia:

  • bigquery.jobs.create
  • storage.objects.create
  • storage.buckets.get (wymagane tylko w przypadku testowania magazynu danych zgodnie z opisem w sekcji Testowanie konfiguracji magazynu danych)

Konfigurowanie Google BigQuery

Zanim wyeksportujesz dane do Google BigQuery:

• Upewnij się, że interfejsy BigQuery i Cloud Resource Manager są włączone w projekcie Google Cloud Platform. Instrukcje znajdziesz w artykule Włączanie interfejsów API. Apigee używa interfejsu Cloud Resource Manager API do sprawdzania uprawnień przed każdym eksportem.
• Sprawdź, czy interfejs BigQuery API jest włączony w projekcie Google Cloud Platform. Instrukcje znajdziesz w artykule Włączanie i wyłączanie interfejsów API.

• Sprawdź, czy do konta usługi są przypisane te role:

  • Użytkownik zadań BigQuery
  • Edytujący dane BigQuery

  Jeśli chcesz zmodyfikować istniejącą rolę lub utworzyć rolę niestandardową, dodaj do niej te uprawnienia:

  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.get
  • bigquery.tables.updateData

Tworzenie magazynu danych

Magazyn danych określa połączenie z repozytorium danych eksportu (Cloud Storage, BigQuery), w tym dane logowania używane do uzyskiwania dostępu do repozytorium danych.

Informacje o magazynie danych logowania Edge

Edge używa skarbca danych logowania do bezpiecznego przechowywania danych logowania używanych do uzyskiwania dostępu do repozytorium danych eksportu. Aby usługa mogła uzyskać dostęp do danych logowania w Edge Credentials Vault, musisz zdefiniować odbiorcę danych logowania.

Podczas tworzenia magazynu danych za pomocą interfejsu Edge, zgodnie z opisem poniżej, Edge automatycznie tworzy konsumenta używanego do uzyskiwania dostępu do danych logowania.

Testowanie konfiguracji magazynu danych

Podczas tworzenia magazynu danych Edge nie testuje ani nie sprawdza, czy Twoje dane logowania i konfiguracja repozytorium danych są prawidłowe. Oznacza to, że możesz utworzyć magazyn danych i nie wykryć żadnych błędów, dopóki nie przeprowadzisz pierwszego eksportu danych.

Możesz też przetestować konfigurację magazynu danych przed jego utworzeniem. Testowanie jest przydatne, ponieważ proces eksportowania dużej ilości danych może trwać długo. Testując dane logowania i konfigurację magazynu danych przed rozpoczęciem pobierania dużych ilości danych, możesz szybko rozwiązać wszelkie problemy z ustawieniami.

Jeśli test się powiedzie, utwórz magazyn danych. Jeśli test się nie powiedzie, napraw błędy i ponownie przetestuj konfigurację. Magazyn danych tworzysz dopiero po pomyślnym zakończeniu testów.

Aby włączyć funkcję testowania:

• Upewnij się, że interfejs Cloud Resource Manager API jest włączony w projekcie Google Cloud Platform. Instrukcje znajdziesz w artykule Włączanie i wyłączanie interfejsów API.

Tworzenie magazynu danych

Aby utworzyć magazyn danych w interfejsie:

1. Zaloguj się na https://apigee.com/edge jako administrator organizacji i wybierz swoją organizację.

   NOTE aby utworzyć magazyn danych, musisz być administratorem organizacji Edge.

2. Na pasku nawigacyjnym po lewej stronie kliknij Administracja > Magazyny danych Analytics. Wyświetli się strona Pamięci danych Analytics.

3. Kliknij przycisk + Dodaj Datastore. Zostanie wyświetlony monit o wybranie typu magazynu danych:

   

4. Wybierz typ miejsca docelowego eksportowanych danych:

   • Google Cloud Storage
   • Google BigQuery,

   Wyświetli się strona konfiguracji:

   

5. Wpisz nazwę magazynu danych.

6. Wybierz dane logowania używane do uzyskiwania dostępu do repozytorium danych. Pojawi się lista dostępnych danych logowania.

   Dane logowania są specyficzne dla typu repozytorium danych. Więcej informacji znajdziesz w artykule Tworzenie konta usługi na potrzeby Cloud Storage lub BigQuery.

   • Jeśli dane logowania zostały już przesłane, wybierz je z menu. Upewnij się, że wybrane dane logowania są odpowiednie dla typu repozytorium danych.

   • Jeśli dodajesz nowe dane logowania do magazynu danych, kliknij Dodaj nowe. W oknie dialogowym wpisz:

     1. Nazwa danych logowania.
     2. Treść danych logowania to klucz konta usługi w formacie JSON, który jest specyficzny dla Twojego repozytorium danych zgodnie z opisem w artykule Tworzenie konta usługi na potrzeby Cloud Storage lub BigQuery.
     3. Kliknij Utwórz.

7. Wpisz właściwości charakterystyczne dla typu repozytorium danych:

   • W przypadku Google Cloud Storage:

     Właściwość	Opis	Wymagany?
     Identyfikator projektu	Identyfikator projektu Google Cloud Platform. Informacje o tworzeniu projektu Google Cloud Platform znajdziesz w dokumentacji Google Cloud Platform w artykule Tworzenie projektów i zarządzanie nimi.	Tak
     Nazwa zasobnika	Nazwa zasobnika w Cloud Storage, do którego chcesz wyeksportować dane analityczne. Przed wyeksportowaniem danych musisz utworzyć zasobnik. Informacje o tworzeniu zasobnika Cloud Storage znajdziesz w artykule Tworzenie zasobników Storage w dokumentacji Google Cloud Platform.	Tak
     Ścieżka	Katalog, w którym będą przechowywane dane analityczne w zasobniku Cloud Storage.	Tak

   • W przypadku BigQuery:

     Właściwość	Opis	Wymagany?
     Identyfikator projektu	Identyfikator projektu Google Cloud Platform. Informacje o tworzeniu projektu Google Cloud Platform znajdziesz w dokumentacji Google Cloud Platform w artykule Tworzenie projektów i zarządzanie nimi.	Tak
     Nazwa zbioru danych	Nazwa zbioru danych BigQuery, do którego chcesz eksportować dane analityczne. Zanim poprosisz o eksport danych, upewnij się, że zbiór danych został utworzony. Aby utworzyć zbiór danych BigQuery, zapoznaj się z artykułem Tworzenie zbiorów danych i korzystanie z nich w dokumentacji Google Cloud Platform.	Tak
     Prefiks tabeli	Prefiks nazw tabel utworzonych na potrzeby danych analitycznych w zbiorze danych BigQuery.	Tak

8. Kliknij Testuj połączenie, aby sprawdzić, czy dane logowania umożliwiają dostęp do repozytorium danych.

   Jeśli test się powiedzie, zapisz magazyn danych.

   Jeśli test się nie powiedzie, rozwiąż problemy i spróbuj ponownie. Najedź kursorem na komunikat o błędzie w interfejsie, aby wyświetlić dodatkowe informacje w dymku.

9. Po pomyślnym zakończeniu testu połączenia zapisz magazyn danych.

Modyfikowanie magazynu danych

Aby zmodyfikować magazyn danych:

1. Zaloguj się na https://apigee.com/edge jako administrator organizacji i wybierz swoją organizację.

2. Na pasku nawigacyjnym po lewej stronie kliknij Administracja > Magazyny danych Analytics. Wyświetli się strona Pamięci danych Analytics.

3. Najedź wskaźnikiem myszy na kolumnę Zmodyfikowano w raporcie, który chcesz zmodyfikować. Pojawią się ikony edytowania i usuwania.

4. Edytuj lub usuń magazyn danych.

5. Jeśli magazyn danych został przez Ciebie zmodyfikowany, kliknij Testuj połączenie, aby sprawdzić, czy dane logowania umożliwiają dostęp do magazynu danych.

   Jeśli test się powiedzie, możesz wyświetlić przykładowe dane w repozytorium danych.

   Jeśli test się nie powiedzie, rozwiąż problemy i spróbuj ponownie.

6. Gdy test połączenia zakończy się pomyślnie, zaktualizuj magazyn danych.

Eksportowanie danych analitycznych

Aby wyeksportować dane analityczne, wyślij żądanie POST do interfejsu API /analytics/exports. W treści żądania przekaż te informacje:

• Nazwa i opis prośby o eksport
• Zakres dat eksportowanych danych (wartość może obejmować tylko 1 dzień)
• Format wyeksportowanych danych
• Nazwa magazynu danych
• Określa, czy w organizacji włączone jest zarabianie.

Przykłady żądań eksportu znajdziesz poniżej. Pełny opis właściwości treści żądania znajdziesz w dokumentacji właściwości żądania eksportu.

Odpowiedź na żądanie POST ma postać:

{
    "self": "/organizations/myorg/environments/test/analytics/exports/a7c2f0dd-1b53-4917-9c42-a211b60ce35b",
    "created": "2017-09-28T12:39:35Z",
    "state": "enqueued"
}

Zwróć uwagę, że właściwość state w odpowiedzi ma wartość enqueued. Żądanie POST działa asynchronicznie. Oznacza to, że po zwróceniu odpowiedzi na żądanie nadal działa w tle. Możliwe wartości parametru state: enqueued, running, completed, failed.

Aby sprawdzić stan prośby o eksport danych, użyj adresu URL zwróconego we właściwości self, zgodnie z opisem w artykule Sprawdzanie stanu prośby o eksport danych z Analytics. Po zakończeniu żądania wartość właściwości state w odpowiedzi jest ustawiana na completed. Następnie możesz uzyskać dostęp do danych analitycznych w repozytorium danych.

Przykład 1. Eksportowanie danych do Cloud Storage

Poniższe żądanie eksportuje pełny zestaw nieprzetworzonych danych z ostatnich 24 godzin ze środowiska test w organizacji myorg. Treści są eksportowane do Cloud Storage w formacie JSON:

curl -X POST -H "Content-Type:application/json" \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }' \
  -u orgAdminEmail:password

Użyj identyfikatora URI określonego przez właściwość self, aby monitorować stan zadania zgodnie z opisem w artykule Wyświetlanie stanu prośby o eksport danych analitycznych.

Przykład 2. Eksportowanie danych do BigQuery

To żądanie eksportuje do BigQuery plik CSV rozdzielany przecinkami:

curl -X POST -H "Content-Type:application/json"  \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -d \
  '{
    "name": "Export query results to BigQuery",
    "description": "One-time export to BigQuery",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "csv",
    "csvDelimiter": ",", 
    "datastoreName": "My BigQuery data repository"
  }' \
  -u orgAdminEmail:password

Uwaga: wyeksportowany plik CSV tworzy tabelę BigQuery z tym prefiksem:

<PREFIX>_<EXPORT_DATE>_api_<UUID>_from_<FROM_DATE>_to_<TO_DATE>

Aby monitorować stan zadania, użyj identyfikatora URI określonego przez właściwość self zgodnie z opisem w artykule Wyświetlanie stanu żądania eksportu danych analitycznych.

Przykład 3. Eksportowanie danych o zarabianiu

Jeśli w środowisku w organizacji włączona jest monetyzacja, możesz przeprowadzić 2 rodzaje eksportu danych:

• Standardowy eksport danych, jak w 2 poprzednich przykładach.
• Eksportowanie danych o zarabianiu, aby eksportować dane dotyczące zarabiania.

Aby wyeksportować dane o zarabianiu, w ładunku żądania określ "dataset":"mint". Aby ustawić tę opcję, organizacja i środowisko muszą obsługiwać zarabianie. W przeciwnym razie pomiń właściwość dataset w ładunku:

  '{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository",
    "dataset":"mint"
  }'

Limity interfejsu Export API

Aby zapobiec nadmiernemu wykorzystywaniu kosztownych wywołań interfejsu API eksportu danych, Edge wymusza limit wywołań interfejsu API /analytics/exports:

• W przypadku organizacji i środowisk, w których nie włączono zarabiania, limit wynosi:

  • 70 wywołań miesięcznie na organizację lub środowisko.

  Jeśli na przykład w organizacji masz 2 środowiska, prod i test, możesz wykonać 70 wywołań interfejsu API miesięcznie w każdym z nich.

• W przypadku organizacji i środowisk z włączoną funkcją zarabiania limit wynosi:

  • 70 wywołań miesięcznie w przypadku każdej organizacji i środowiska w przypadku danych standardowych.
  • 70 wywołań miesięcznie w przypadku każdej organizacji i każdego środowiska w odniesieniu do danych o zarabianiu.

  Jeśli na przykład włączysz zarabianie w organizacji prod, możesz wykonać 70 wywołań interfejsu API w przypadku danych standardowychi 70 dodatkowych wywołań interfejsu API w przypadku danych o zarabianiu.

Jeśli przekroczysz limit wywołań, interfejs API zwróci odpowiedź HTTP 429.

Wyświetlanie stanu wszystkich próśb o eksport danych analitycznych

Aby wyświetlić stan wszystkich próśb o eksport danych analitycznych, wyślij żądanie GET do /analytics/exports.

Na przykład to żądanie zwraca stan wszystkich próśb o eksportowanie danych analitycznych w środowisku test w organizacji myorg:

curl -X GET \
  "https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports" \
  -u email:password

Poniżej znajdziesz przykład odpowiedzi z 2 prośbami o eksport – jedną w kolejce (utworzoną i znajdującą się w kolejce) i jedną zrealizowaną:

[
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/e8b8db22-fe03-4364-aaf2-6d4f110444ba",
    "name": "Export results To Cloud Storage",
    "description": "One-time export to Google Cloud Storage",
    "userId": "my@email.com",
    "datastoreName": "My Cloud Storage data store",
    "executionTime": "36 seconds",
    "created": "2018-09-28T12:39:35Z",
    "updated": "2018-09-28T12:39:42Z",
    "state": "enqueued"
  },
  {
    "self":
"/v1/organizations/myorg/environments/test/analytics/exports/9870987089fe03-4364-aaf2-6d4f110444ba"
    "name": "Export raw results to BigQuery",
    "description": "One-time export to BigQuery",
    ... 
  }
]

Sprawdzanie stanu prośby o eksport danych analitycznych

Aby wyświetlić stan konkretnej prośby o eksport danych analitycznych, wyślij żądanie GET do /analytics/exports/{exportId}, gdzie {exportId} to identyfikator powiązany z prośbą o eksport danych analitycznych.

Na przykład to żądanie zwraca stan żądania eksportu danych analitycznych o identyfikatorze 4d6d94ad-a33b-4572-8dba-8677c9c4bd98.

curl -X GET \
"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98" \
-u email:password

Oto przykład odpowiedzi:

{
  "self":
"/v1/organizations/myorg/environments/test/analytics/exports/4d6d94ad-a33b-4572-8dba-8677c9c4bd98",
  "name": "Export results To Cloud Storage",
  "description": "One-time export to Google Cloud Storage",
  "userId": "my@email.com",
  "datastoreName": "My Cloud Storage data store",
  "executionTime": "36 seconds",
  "created": "2018-09-28T12:39:35Z",
  "updated": "2018-09-28T12:39:42Z",
  "state": "enqueued"
}

Jeśli eksport danych analitycznych nie zwróci żadnych danych, wartość executionTime zostanie ustawiona na „0 sekund”.

Odwołanie do usługi w żądaniu eksportu

W tej tabeli opisano właściwości, które możesz przekazać w treści żądania w formacie JSON podczas eksportowania danych analitycznych.

"dateRange": {
    "start": "2018-07-29",
    "end": "2018-07-30"
}

Na przykład:

{
    "name": "Export raw results to Cloud Storage",
    "description": "Export raw results to Cloud Storage for last 24 hours",
    "dateRange": {
      "start": "2018-06-08", 
      "end": "2018-06-09"
    },
    "outputFormat": "json",
    "datastoreName": "My Cloud Storage data repository"
  }