Korzystanie z asynchronicznego interfejsu API raportów niestandardowych

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

Edge Analytics udostępnia bogaty zestaw interaktywnych paneli, generatorów raportów niestandardowych i powiązanych funkcji. Te funkcje mają jednak charakter interaktywny: przesyłasz żądanie za pomocą interfejsu API lub interfejsu użytkownika, a żądanie jest blokowane, dopóki serwer Analytics nie odpowie.

Jednak żądania dotyczące funkcji analitycznych mogą zostać przerwane, jeśli ich realizacja potrwa zbyt długo. Jeśli żądanie zapytania wymaga przetworzenia dużej ilości danych (np. setek GB), może się nie udać z powodu limitu czasu.

Przetwarzanie zapytań asynchronicznie umożliwia wysyłanie zapytań dotyczących bardzo dużych zbiorów danych i pobieranie wyników w późniejszym czasie. Jeśli zauważysz, że Twoje interaktywne zapytania są przerywane, możesz rozważyć użycie zapytania offline. Oto kilka sytuacji, w których przetwarzanie zapytań asynchronicznie może być dobrą alternatywą:

• analizowanie i tworzenie raportów obejmujących długie przedziały czasu;
• analizowanie danych za pomocą różnych wymiarów grupowania i innych ograniczeń, które zwiększają złożoność zapytania;
• Zarządzanie zapytaniami, gdy zauważysz, że ilość danych znacznie wzrosła w przypadku niektórych użytkowników lub organizacji.

Z tego dokumentu dowiesz się, jak zainicjować zapytania asynchroniczne za pomocą interfejsu API. Możesz też użyć interfejsu użytkownika w sposób opisany w sekcji Uruchamianie raportu niestandardowego.

Porównanie interfejsu API do raportów z interfejsem użytkownika

W artykule Tworzenie raportów niestandardowych i zarządzanie nimi znajdziesz informacje o tym, jak używać interfejsu Edge do tworzenia i uruchamiania raportów niestandardowych. Możesz je uruchamiać synchronicznie lub asynchronicznie.

Większość koncepcji dotyczących generowania raportów niestandardowych za pomocą interfejsu użytkownika ma zastosowanie do korzystania z interfejsu API. Oznacza to, że podczas tworzenia raportów niestandardowych za pomocą interfejsu API możesz określać dane, wymiary i filtry wbudowane w Edge oraz wszelkie dane niestandardowe utworzone za pomocą reguły StatisticsCollector.

Najważniejsze różnice między raportami generowanymi w interfejsie a w interfejsie API polegają na tym, że raporty generowane za pomocą interfejsu API są zapisywane w plikach CSV lub JSON (oznaczonych znakami nowej linii) zamiast w raporcie wizualnym wyświetlanym w interfejsie.

Limity w wersji hybrydowej Apigee

Apigee hybrid nakłada limit rozmiaru 30 MB na zbiór danych z wynikiem.

Jak przesłać asynchroniczne zapytanie analityczne

Aby przesłać asynchroniczne zapytania analityczne, wykonaj 3 kroki:

1. Prześlij zapytanie.

2. Pobierz stan zapytania.

3. Pobierz wyniki zapytania.

Krok 1. Przesyłanie zapytania

Musisz wysłać żądanie POST do interfejsu API /queries. Ten interfejs API informuje Edge, aby przetwarzał Twoje żądanie w tle. Jeśli przesłanie zapytania się powiedzie, interfejs API zwróci kod stanu 201 i identyfikator, którego użyjesz do odwołania się do zapytania w kolejnych krokach.

Na przykład:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

Treść żądania to opis zapytania w formacie JSON. W treści pliku JSON określ dane, wymiary i filtry, które definiują raport.

Poniżej znajduje się przykładowy plik json-query-file:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

Pełny opis składni treści żądania znajdziesz w sekcji Informacje o treści żądania.

Przykładowa odpowiedź:

Zwróć uwagę, że identyfikator zapytania 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd jest uwzględniony w odpowiedzi. Oprócz stanu HTTP 201 wartość state w atrybucie enqueued oznacza, że żądanie zostało zrealizowane.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

Krok 2. Pobieranie stanu zapytania

Aby uzyskać stan zapytania, wyślij wywołanie GET. Musisz podać identyfikator zapytania zwrócony przez wywołanie metody POST. Na przykład:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

Przykładowe odpowiedzi:

Jeśli zapytanie jest nadal w trakcie realizacji, otrzymasz taką odpowiedź, gdzie state to running:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

Po pomyślnym zakończeniu działania zapytania zobaczysz odpowiedź podobną do tej, w której state ma wartość completed:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

Krok 3. Pobieranie wyników zapytania

Gdy stan zapytania to completed, możesz użyć interfejsu API get results, aby pobrać wyniki. Identyfikator zapytania to ponownie 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

Aby pobrać pobrany plik, musisz skonfigurować używane narzędzie, aby zapisywało pobrane pliki w Twoim systemie. Na przykład:

• Jeśli używasz cURL, możesz użyć opcji -O -J, jak pokazano powyżej.

• Jeśli używasz Postmana, kliknij przycisk Zapisz i pobierz. W tym przypadku pobierany jest plik ZIP o nazwie response.

• Jeśli używasz przeglądarki Chrome, pobieranie jest akceptowane automatycznie.

Jeśli żądanie się powiedzie i jest niezerowy zbiór wyników, wynik zostanie pobrany na klienta jako skompresowany plik JSON (oddzielony znakami nowego wiersza). Nazwa pobranego pliku będzie następująca:

OfflineQueryResult-<query-id>.zip

Na przykład:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

Plik ZIP zawiera plik zarchiwum .gz z wynikami w formacie JSON. Aby uzyskać dostęp do pliku JSON, rozpakuj pobrany plik, a potem użyj polecenia gzip, aby wyodrębnić plik JSON:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

Treść żądania

W tej sekcji opisaliśmy wszystkie parametry, których możesz używać w ciele żądania JSON dla zapytania. Szczegółowe informacje o danych i wymiarach, których możesz używać w zapytaniu, znajdziesz w artykule [GA4] Informacje referencyjne Analytics.

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

Składnia wyrażenia filtra

W tej sekcji znajdziesz opis tokenów, których możesz używać do tworzenia wyrażeń filtrujących w ciele żądania. Na przykład to wyrażenie używa tokena „ge” (większe lub równe):

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

Ograniczenia i wartości domyślne

Poniżej znajdziesz listę ograniczeń i wartości domyślnych funkcji asynchronicznego przetwarzania zapytań.

Informacje o wynikach zapytania

Poniżej znajdziesz przykładowy wynik w formacie JSON. Dane wyjściowe to wiersze JSON rozdzielone znakiem nowego wiersza:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

Wyniki możesz pobierać z adresu URL do momentu wygaśnięcia danych w repozytorium. Zobacz Ograniczenia i wartości domyślne.

Przykłady

Przykład 1. Suma liczby wiadomości

Zapytanie o sumę liczby wiadomości w ciągu ostatnich 60 minut.

Zapytanie

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Treść żądania z last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Przykład 2. Niestandardowy zakres czasu

Zapytanie z użyciem niestandardowego zakresu czasowego.

Zapytanie

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Treść żądania z last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Przykład 3. Transakcje na minutę

Zapytanie dotyczące danych o transakcjach na minutę (tpm).

Zapytanie

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

Treść żądania z tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Przykładowy wynik

Wycinek z pliku wyników:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

Przykład 4. Używanie wyrażenia filtra

Zapytanie z wyrażeniem filtra, które używa operatora logicznego.

Zapytanie

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

Treść żądania z pliku filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Przykład 5. Przekazywanie wyrażenia w parametrze danych

Zapytanie z wyrażeniem przekazanym jako część parametru danych. Możesz używać tylko prostych wyrażeń z jednym operatorem.

Zapytanie

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

Treść żądania z metricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

Jak przesłać asynchroniczne zapytanie o raport o zarabianiu

Możesz rejestrować wszystkie transakcje z zarabianiem w danym zakresie czasowym zgodnie z określonym zestawem kryteriów, wykonując czynności opisane w tej sekcji.

Podobnie jak w przypadku asynchronicznych zapytań analitycznych, asynchroniczne zapytania dotyczące raportu o zarabianiu możesz wysyłać w 3 kroki: (1) prześlij zapytanie, (2) uzyskaj stan zapytania i (3) pobierz wyniki zapytania.

Krok 1, czyli przesyłanie zapytania, opisaliśmy poniżej.

Kroki 2 i 3 są takie same jak w przypadku asynchronicznych zapytań analitycznych. Więcej informacji znajdziesz w artykule Jak wysłać asynchroniczne zapytanie Analytics.

Aby przesłać zapytanie o raport zarabiania asynchronicznego, wyślij żądanie POST do adresu /mint/organizations/org_id/async-reports.

Opcjonalnie możesz określić środowisko, podając parametr zapytania environment. Jeśli nie podasz żadnej wartości, parametr zapytania zostanie domyślnie ustawiony na prod. Na przykład:

/mint/organizations/org_id/async-reports?environment=prod

W treści żądania podaj te kryteria wyszukiwania:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

Na przykład żądanie poniżej generuje asynchroniczny raport o zarabianiu za miesiąc czerwiec 2017 r. dla wskazanego produktu interfejsu API i identyfikatora dewelopera. Daty i godziny w raportach fromDate i toDate są podane w czasie UTC/GMT i mogą zawierać godziny.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password