Korzystanie z asynchronicznego interfejsu API raportów niestandardowych

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

Edge Analytics udostępnia bogaty zestaw interaktywnych paneli informacyjnych, niestandardowych generatorów raportów i powiązanych funkcji. Te funkcje powinny być jednak interaktywne: gdy prześlesz żądanie do interfejsu API lub interfejsu użytkownika, zostanie ono zablokowane do czasu, aż serwer analityki udzieli odpowiedzi.

Żądania Analytics mogą jednak przekroczyć limit czasu, jeśli ich wykonanie trwa zbyt długo. Jeśli żądanie zapytania musi przetworzyć dużą ilość danych (np. 100 GB), może się zakończyć niepowodzeniem z powodu przekroczenia limitu czasu.

Asynchroniczne przetwarzanie zapytań umożliwia wykonywanie zapytań dotyczących bardzo dużych zbiorów danych i pobieranie wyników w późniejszym czasie. Możesz rozważyć użycie zapytania offline, gdy stwierdzisz, że upłynął limit czasu zapytań interaktywnych. Oto kilka sytuacji, w których asynchroniczne przetwarzanie zapytań może być dobrym rozwiązaniem:

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

W tym dokumencie opisujemy, jak inicjować zapytania asynchroniczne przy użyciu interfejsu API. Możesz też użyć interfejsu użytkownika w sposób opisany w sekcji Generowanie raportu niestandardowego.

Porównanie interfejsu Reports API z UI

Informacje o tworzeniu raportów niestandardowych i zarządzaniu nimi zawierają opis sposobu korzystania z interfejsu Edge do tworzenia i uruchamiania raportów niestandardowych. Raporty te można generować synchronicznie lub asynchronicznie.

Większość koncepcji generowania raportów niestandardowych za pomocą interfejsu użytkownika dotyczy korzystania z interfejsu API. Oznacza to, że podczas tworzenia raportów niestandardowych za pomocą interfejsu API określasz metrics, wymiary i filtry wbudowane w Edge oraz wszelkie dane niestandardowe utworzone za pomocą zasady StatisticsCollector.

Główne różnice między raportami wygenerowanymi w interfejsie użytkownika i w interfejsie API polegają na tym, że raporty generowane przez interfejs API są zapisywane w plikach CSV lub JSON (rozdzielanych znakami nowego wiersza), a nie w raportach wizualnych wyświetlanych w interfejsie.

Limity w Apigee hybrydowym

Apigee hybrydowy wymusza limit rozmiaru zbioru danych wynikowego na poziomie 30 MB.

Jak utworzyć asynchroniczne zapytanie analityczne

Aby utworzyć asynchroniczne zapytania analityczne, wykonaj 3 kroki:

1. Prześlij zapytanie.

2. Pobierz stan zapytania.

3. Pobierz wyniki zapytania.

Krok 1. Wyślij zapytanie

Musisz wysłać żądanie POST do interfejsu API /queries. Ten interfejs API informuje Edge, że ma przetworzyć żądanie w tle. Jeśli przesłanie zapytania się powiedzie, interfejs API zwróci stan 201 i identyfikator, którego będziesz używać do odwoływania się 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 jego opis w formacie JSON. W treści JSON określ metrics, 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 poniżej w sekcji Informacje o treści żądania.

Przykładowa odpowiedź:

Pamiętaj, że w odpowiedzi znajduje się identyfikator zapytania 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd. Oprócz stanu HTTP 201 wartość state parametru 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

Wykonaj wywołanie GET, aby zażądać stanu zapytania. Podajesz identyfikator zapytania zwrócony z wywołania 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 wykonywane, otrzymasz odpowiedź podobną do tej, w której 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 zakończeniu wykonywania 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 tak, aby zapisało pobrany plik w Twoim systemie. Na przykład:

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

• Jeśli korzystasz z aplikacji Postman, musisz wybrać przycisk Zapisz i pobierz. W takim przypadku pobierany jest plik ZIP o nazwie response.

• Jeśli korzystasz z przeglądarki Chrome, pobieranie jest akceptowane automatycznie.

Jeśli żądanie się powiedzie i pojawi się zbiór wyników większy niż 0, wynik zostanie pobrany do klienta jako skompresowany plik JSON (z nowym wierszem rozdzielanym znakami nowego wiersza). Pobrany plik będzie mieć taką nazwę:

OfflineQueryResult-<query-id>.zip

Na przykład:

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

Plik ZIP zawiera plik archiwum .gz z wynikami JSON. Aby uzyskać dostęp do pliku JSON, rozpakuj go, a potem rozpakuj go za pomocą polecenia gzip:

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

Treść żądania

W tej sekcji opisujemy wszystkie parametry, których możesz używać w treści żądania JSON w przypadku zapytania. Szczegółowe informacje o danych i wymiarach, których możesz użyć w zapytaniu, znajdziesz w materiałach referencyjnych dotyczących 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żeń filtra

W tej sekcji znajdziesz opis tokenów, których możesz używać do tworzenia wyrażeń filtra w treści żądania. Na przykład poniższe wyrażenie używa tokena „ge” (większego lub równego):

"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ń.

Wyniki zapytania

Poniżej znajdziesz przykładowy wynik w formacie JSON. Wynik składa się z wierszy JSON rozdzielonych nowym separatorem wierszy:

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

Możesz pobierać wyniki z adresu URL do wygaśnięcia danych w repozytorium. Zobacz Ograniczenia i ustawienia domyślne.

Przykłady

Przykład 1: suma liczby wiadomości

Zapytanie o sumę liczby wiadomości z 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 pliku 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 czasu.

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 pliku 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 o dane dotyczące transakcji 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 pliku 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

Fragment 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. Wykorzystanie wyrażenia filtra

Zapytanie z wyrażeniem filtra z operatorem logicznym.

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 atrybutufilterCombo.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 wskaźników

Zapytanie z wyrażeniem przekazywanym w parametrze wskaźników. 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 MetricExpression.json

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

Jak utworzyć zapytanie dotyczące raportu Generowanie przychodu asynchronicznego

Korzystając z instrukcji opisanych w tej sekcji, możesz rejestrować wszystkie udane transakcje zarabiania w danym przedziale czasu dla określonego zestawu kryteriów.

Podobnie jak w przypadku zapytań analityki asynchronicznej, zapytania dotyczące asynchronicznego raportu zarabiania wykonujesz w 3 krokach: (1) przesłanie zapytania, (2) sprawdzenie stanu zapytania i (3) pobranie wyników zapytania.

Krok 1, czyli przesyłanie zapytania, został opisany poniżej.

Kroki 2 i 3 są dokładnie takie same jak w przypadku zapytań dotyczących asynchronicznej analizy danych. Więcej informacji znajdziesz w artykule Jak utworzyć zapytanie asynchroniczne.

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

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

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

W treści żądania określ następujące kryteria wyszukiwania.

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

Na przykład to żądanie wygeneruje asynchroniczny raport zarabiania za czerwiec 2017 roku dla określonego interfejsu API i identyfikatora dewelopera. Daty i godziny w raporcie 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