Eksportowanie danych z Analytics

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Skonfiguruj uprawnienia przypisanych agentów usługi

Aby skonfigurować uprawnienia dla przypisanych agentów usługi, w ramach przygotowań do zmian opisanych powyżej wykonaj poniższe czynności.

1. Znajdź nazwę agenta usługi Google Cloud, wpisując 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'

   było ORG. 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 uprawnień 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 value widoczna 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

Eksportuj format danych

Eksportuj dane analityczne do jednego z tych formatów:

• Plik rozdzielany przecinkami (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 Informacje o właściwościach żądania eksportu .

• JSON (rozdzielany znakiem nowej linii)

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

Wyeksportowane dane obejmują wszystkie dane i wymiary Analytics wbudowane w Edge, a także wszelkie niestandardowe dane analityczne, które dodasz. Opis wyeksportowanych danych znajdziesz w artykule Informacje o danych, wymiarach i filtrach Analytics.

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

• Google Cloud Storage
• Google BigQuery,

Omówienie procesu eksportowania

Poniżej znajdziesz podsumowanie procedury eksportowania danych Analytics:

1. Skonfiguruj repozytorium danych (Cloud Storage lub BigQuery), do którego mają być eksportowane dane. Musisz się upewnić, że repozytorium danych zostało prawidłowo skonfigurowane, a konto usługi używane do zapisywania danych w repozytorium danych ma odpowiednie uprawnienia.

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

   Podczas tworzenia magazynu danych dane logowania do repozytorium danych są przesyłane do Vault danych logowania na serwerach brzegowych, aby je bezpiecznie przechowywać. Mechanizm eksportu danych używa następnie tych danych logowania, aby zapisać informacje w Twoim repozytorium danych.

3. Zainicjuj eksport danych za pomocą interfejsu API eksportu danych. Eksport danych jest uruchamiany asynchronicznie w tle.

4. Aby określić, kiedy eksport danych się zakończy, użyj interfejsu API eksportu danych.

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

W sekcjach poniżej znajdziesz bardziej szczegółowe informacje o tych czynnościach.

Skonfiguruj repozytorium danych

Mechanizm eksportu danych analitycznych zapisuje dane w Cloud Storage lub BigQuery. Aby tak się stało:

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

Tworzenie konta usługi dla Cloud Storage lub BigQuery

Konto usługi to typ konta Google, które należy do aplikacji, a nie do użytkownika. Następnie aplikacja uzyskuje dostęp do usługi za pomocą konta usługi.

Konto usługi ma klucz konta usługi reprezentowany przez ciąg znaków JSON. Podczas tworzenia magazynu danych Edge, który określa połączenie z Twoim repozytorium danych, przekazujesz do niego ten klucz. Następnie mechanizm eksportu danych używa tego klucza, aby uzyskać dostęp 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. Aby utworzyć klucz usługi i pobrać wymagany ładunek, przeczytaj sekcję Tworzenie kluczy konta usługi i zarządzanie nimi w dokumentacji Google Cloud Platform.

Na przykład przy pierwszym pobieraniu klucz zostanie 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:

• Sprawdź, czy w projekcie Google Cloud Platform są włączone interfejsy API BigQuery i Cloud Resource Manager. Instrukcje znajdziesz w artykule Włączanie interfejsów API. Apigee używa interfejsu BigQuery API do wykorzystywania funkcji BigQuery Export podczas eksportowania do Cloud Storage oraz interfejsu Cloud Resource Manager API do sprawdzania uprawnień przed każdym eksportem.

• Sprawdź, czy konto usługi jest przypisane do tych ról:

  • Użytkownik zadań BigQuery
  • Tworzący obiekty Cloud Storage
  • Administrator miejsca na dane (wymagany tylko do testowania magazynu danych zgodnie z opisem w sekcji Testowanie konfiguracji magazynu danych). Jeśli ta rola jest zbyt obszerna, możesz zamiast niej dodać uprawnienie storage.buckets.get do istniejącej roli.

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

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

Konfigurowanie Google BigQuery

Zanim wyeksportujesz dane do Google BigQuery:

• Sprawdź, czy w projekcie Google Cloud Platform są włączone interfejsy API BigQuery i Cloud Resource Manager. 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 w projekcie Google Cloud Platform włączony jest interfejs BigQuery API. Instrukcje znajdziesz w artykule Włączanie i wyłączanie interfejsów API.

• Sprawdź, czy konto usługi jest przypisane do tych ról:

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

  Jeśli chcesz zmienić 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

Utwórz magazyn danych

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

Informacje o Vault danych logowania na serwerach brzegowych

Edge używa magazynu 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 Vault danych logowania na serwerach brzegowych, musisz zdefiniować klienta danych logowania.

Podczas tworzenia magazynu danych przy użyciu interfejsu użytkownika Edge w sposób opisany poniżej Edge automatycznie tworzy konsumenta używanego do uzyskiwania dostępu do danych logowania.

Testowanie konfiguracji magazynu danych

Gdy tworzysz magazyn 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 wykrywać żadnych błędów, dopóki nie uruchomisz pierwszego eksportu danych.

Możesz też przetestować konfigurację magazynu danych, zanim ją utworzysz. Testowanie jest przydatne, ponieważ wykonywanie dużego procesu eksportu danych może zająć dużo czasu. Testując swoje dane logowania i konfigurację magazynu danych, zanim zaczniesz pobierać duże ilości danych, możesz szybko rozwiązać problemy z ustawieniami.

Jeśli test się powiedzie, utwórz magazyn danych. Jeśli test się nie powiedzie, napraw błędy, a potem sprawdź konfigurację jeszcze raz. Magazyn danych tworzysz dopiero wtedy, gdy testy zakończą się powodzeniem.

Aby włączyć funkcję testową:

• Sprawdź, czy w projekcie Google Cloud Platform włączony jest interfejs Cloud Resource Manager API. Instrukcje znajdziesz w artykule Włączanie i wyłączanie interfejsów API.

Utwórz magazyn danych

Aby utworzyć magazyn danych w interfejsie użytkownika:

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

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

2. Na pasku nawigacyjnym po lewej stronie wybierz Administracja > Magazyny Datastore Analytics. Pojawi się strona Zbiory danych Analytics.

3. Kliknij przycisk + Dodaj Datastore. Pojawi się prośba o wybranie typu magazynu danych:

   

4. Wybierz typ celu eksportu danych:

   • Google Cloud Storage
   • Google BigQuery,

   Pojawi się strona konfiguracji:

   

5. Wpisz nazwę magazynu danych.

6. Wybierz dane logowania, które umożliwiają dostęp 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 dla Cloud Storage lub BigQuery.

   • Jeśli dane logowania zostały już przesłane, wybierz je na liście. Pamiętaj, aby wybrać dane logowania odpowiednie dla typu repozytorium danych.

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

     1. Pole Nazwa danych logowania.
     2. Treść danych logowania to klucz konta usługi JSON przypisany do Twojego repozytorium danych zgodnie z definicją podaną w sekcji Tworzenie konta usługi dla Cloud Storage lub BigQuery.
     3. Wybierz Utwórz.

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

   • W przypadku Google Cloud Storage:

     Właściwość	Opis	Wymagana?
     Identyfikator projektu	Identyfikator projektu Google Cloud Platform. Aby utworzyć projekt Google Cloud Platform, przeczytaj sekcję Tworzenie projektów i zarządzanie nimi w dokumentacji Google Cloud Platform.	Tak
     Nazwa zasobnika	Nazwa zasobnika w Cloud Storage, do którego chcesz eksportować dane analityczne. Zanim wyeksportujesz dane, zasobnik musi istnieć. Aby utworzyć zasobnik Cloud Storage, przeczytaj sekcję Tworzenie zasobników Cloud Storage w dokumentacji Google Cloud Platform.	Tak
     Ścieżka	Katalog, w którym w zasobniku Cloud Storage mają być przechowywane dane analityczne.	Tak

   • W BigQuery:

     Właściwość	Opis	Wymagana?
     Identyfikator projektu	Identyfikator projektu Google Cloud Platform. Aby utworzyć projekt Google Cloud Platform, przeczytaj sekcję Tworzenie projektów i zarządzanie nimi w dokumentacji Google Cloud Platform.	Tak
     Nazwa zbioru danych	Nazwa zbioru danych BigQuery, do którego chcesz eksportować dane analityczne. Zanim poprosisz o eksport danych, sprawdź, czy zbiór danych został utworzony. Aby utworzyć zbiór danych BigQuery, przeczytaj artykuł Tworzenie i używanie zbiorów danych w dokumentacji Google Cloud Platform.	Tak
     Prefiks tabeli	Prefiks nazw tabel utworzonych na potrzeby danych analitycznych w zbiorze danych BigQuery.	Tak

8. Wybierz Połączenie testowe, aby upewnić się, że można użyć danych logowania do uzyskania dostępu 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, by wyświetlić dodatkowe informacje w etykietce.

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

Modyfikowanie magazynu danych

Aby zmodyfikować magazyn danych:

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

2. Na pasku nawigacyjnym po lewej stronie wybierz Administracja > Magazyny Datastore Analytics. Pojawi się strona Zbiory danych Analytics.

3. Aby wprowadzić zmiany, najedź kursorem myszy na kolumnę Zmodyfikowano w raporcie. Pojawi się ikona edycji i usuwania.

4. Edytuj lub usuń magazyn danych.

5. Jeśli magazyn danych był edytowany, wybierz Połączenie testowe, aby upewnić się, że można użyć tych danych logowania, aby uzyskać 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. Po pomyślnym zakończeniu testu połączenia zaktualizuj magazyn danych.

Eksportowanie danych analitycznych

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

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

Poniżej znajdziesz przykłady próśb o eksport. Pełny opis właściwości treści żądania znajdziesz w artykule Dokumentacja właściwości żądania eksportu.

Odpowiedź żądania POST ma postać:

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

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

Użyj adresu URL zwróconego we właściwości self, aby wyświetlić stan prośby o eksport danych zgodnie z opisem w sekcji Wyświetlanie stanu żądania eksportu danych Analytics. Po zakończeniu żądania wartość właściwości state w odpowiedzi jest ustawiana na completed. Dzięki temu uzyskasz dostęp do danych analitycznych w swoim repozytorium danych.

Przykład 1. Eksportowanie danych do Cloud Storage

To żądanie eksportuje pełny zbiór nieprzetworzonych danych z ostatnich 24 godzin ze środowiska testowego organizacji myorg. Treść jest eksportowana 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 we właściwości self, aby monitorować stan zadania zgodnie z opisem w sekcji Wyświetlanie stanu żądania eksportu 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>

Użyj identyfikatora URI określonego we właściwości self, aby monitorować stan zadania zgodnie z opisem w sekcji Wyświetlanie stanu żądania eksportu danych analitycznych.

Przykład 3. Eksportowanie danych o przychodach

Jeśli w środowisku organizacji włączone jest zarabianie, możesz wykonywać 2 typy eksportów danych:

• Standardowy eksport danych zgodnie z opisem w 2 poprzednich przykładach.
• Eksportowanie danych dotyczących generowania przychodu w celu eksportowania danych związanych z generowaniem przychodu.

Aby wyeksportować dane dotyczące zarabiania, w ładunku żądania podaj "dataset":"mint". Aby można było ustawić tę opcję, organizacja i środowisko muszą obsługiwać generowanie przychodu. 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"
  }'

Informacje o limitach interfejsu API eksportu

Aby zapobiec nadmiernemu wykorzystaniu 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 połączeń miesięcznie na organizację/środowisko.

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

• W organizacjach i środowiskach z włączoną funkcją zarabiania limit wynosi:

  • 70 wywołań miesięcznie w każdej organizacji i środowisku w przypadku standardowych danych.
  • 70 połączeń miesięcznie w każdej organizacji i każdym środowisku w przypadku danych dotyczących przychodów.

  Jeśli na przykład włączysz zarabianie w organizacji prod, możesz wykonać 70 wywołań interfejsu API w przypadku standardowych danych i 70 dodatkowych wywołań interfejsu API w przypadku danych dotyczących zarabiania.

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

Wyświetlanie stanu wszystkich żądań eksportu Analytics

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

Na przykład to żądanie zwraca stan wszystkich żądań eksportu Analytics dotyczących środowiska 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 zawierającej 2 żądania eksportu: jedno umieszczone w kolejce (utworzone i w kolejce), a jedno ukończone:

[
  {
    "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",
    ... 
  }
]

Wyświetlanie stanu żądania eksportu danych analitycznych

Aby wyświetlić stan konkretnego żądania eksportu danych Analytics, wyślij do /analytics/exports/{exportId} żądanie GET, gdzie {exportId} to identyfikator powiązany z żądaniem eksportu danych Analytics.

To żądanie zawiera np. stan żądania eksportu Analytics 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

Poniżej znajdziesz przykładową odpowiedź:

{
  "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 statystyk nie zwróci żadnych danych Analytics, executionTime ma wartość „0 sekund”.

Dokumentacja właściwości żądania eksportu

W tabeli poniżej opisujemy właściwości, które można przekazać w treści żądania w formacie JSON podczas eksportowania danych Analytics.

"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"
  }