Korzystanie z asynchronicznego interfejsu API raportów niestandardowych

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

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 API lub interfejsu, a żądanie jest blokowane, dopóki serwer analityczny nie udzieli odpowiedzi.

Jeśli jednak przetwarzanie zapytań analitycznych trwa zbyt długo, może dojść do przekroczenia limitu czasu. Jeśli zapytanie musi przetworzyć dużą ilość danych (np. setki gigabajtów), może się nie powieść z powodu przekroczenia limitu czasu.

Asynchroniczne przetwarzanie zapytań umożliwia wysyłanie zapytań dotyczących bardzo dużych zbiorów danych i pobieranie wyników w późniejszym czasie. Jeśli zapytania interaktywne przekraczają limit czasu, możesz użyć zapytania offline. Oto kilka sytuacji, w których asynchroniczne przetwarzanie zapytań może być dobrą alternatywą:

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

W tym dokumencie opisujemy, jak inicjować zapytania asynchroniczne za pomocą interfejsu API. Możesz też użyć interfejsu, jak opisano w sekcji Uruchamianie raportu niestandardowego.

Porównanie interfejsu Reports API z interfejsem

W artykule Tworzenie raportów niestandardowych i zarządzanie nimi znajdziesz informacje o tym, jak tworzyć i uruchamiać raporty niestandardowe w interfejsie Edge. Możesz je uruchamiać synchronicznie lub asynchronicznie.

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

Główne różnice między raportami generowanymi w interfejsie a raportami generowanymi w interfejsie API polegają na tym, że raporty generowane w interfejsie API są zapisywane w plikach CSV lub JSON (rozdzielonych znakiem nowego wiersza), a nie w postaci raportu wizualnego wyświetlanego w interfejsie.

Limity w Apigee Hybrid

Apigee hybrid wymusza limit rozmiaru zestawu danych wynikowych wynoszący 30 MB.

Jak utworzyć asynchroniczne zapytanie analityczne

Asynchroniczne zapytania analityczne wykonuje się w 3 krokach:

1. Prześlij zapytanie.

2. Pobierz stan zapytania.

3. Pobierz wyniki zapytania.

Krok 1. Prześlij zapytanie

Musisz wysłać żądanie POST do interfejsu API /queries. Ten interfejs API informuje Edge, że ma przetworzyć Twoje żądanie w tle. Jeśli przesłanie zapytania się powiedzie, interfejs API zwróci stan 201 i identyfikator, którego będziesz używać w dalszych krokach do odwoływania się do zapytania.

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 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 Treść żądania poniżej.

Przykładowa odpowiedź:

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

Wyślij wywołanie GET, aby poprosić o stan zapytania. Podaj identyfikator zapytania zwrócony przez wywołanie 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 toku, otrzymasz odpowiedź podobną do tej, w której state ma wartość 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 zapytania zobaczysz odpowiedź podobną do tej, w której wartość state jest ustawiona na 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 get results API, 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ć plik, musisz skonfigurować używane narzędzie tak, aby zapisywało pobrany plik w 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, musisz kliknąć przycisk Zapisz i pobierz. W takim przypadku pobierany jest plik ZIP o nazwie response.

• Jeśli korzystasz z przeglądarki Chrome, pobieranie zostanie zaakceptowane automatycznie.

Jeśli żądanie zostanie zrealizowane i zestaw wyników nie będzie pusty, wynik zostanie pobrany na klienta jako skompresowany plik JSON (rozdzielany znakami nowego wiersza). Nazwa pobranego pliku będzie wyglądać tak:

OfflineQueryResult-<query-id>.zip

Na przykład:

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

Plik ZIP zawiera plik archiwum .gz z wynikami w formacie JSON. Aby uzyskać dostęp do pliku JSON, rozpakuj pobrany plik, a następnie 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

Informacje o treści żądania

W tej sekcji opisujemy każdy z parametrów, których możesz użyć w treści żądania JSON w przypadku zapytania. Szczegółowe informacje o danych i wymiarach, których możesz używać w zapytaniu, znajdziesz w dokumentacji 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

Ta sekcja zawiera opis tokenów, których możesz używać do tworzenia wyrażeń filtra w treści żądania. Na przykład to wyrażenie używa tokena „ge” (większe od 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 przetwarzania zapytań asynchronicznych.

Informacje o wynikach zapytania

Poniżej znajdziesz przykładowy wynik w formacie JSON. Dane wyjściowe składają się z wierszy JSON oddzielonych separatorem 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 pobrać z adresu URL do czasu 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 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 dat

Wykonywanie zapytań 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 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 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 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 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 przekazywanym w ramach parametru metrics. Możesz używać tylko prostych wyrażeń z 1 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 pliku metricsExpression.json

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

Jak wysłać zapytanie do asynchronicznego raportu o zarabianiu

Wykonując czynności opisane w tej sekcji, możesz rejestrować wszystkie transakcje generujące przychody w określonym przedziale czasu dla konkretnego zestawu kryteriów.

Podobnie jak w przypadku asynchronicznych zapytań do Analytics, asynchroniczne zapytania do raportów o zarabianiu wykonuje się w 3 krokach: (1) przesłanie zapytania, (2) uzyskanie stanu zapytania i (3) pobranie wyników zapytania.

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

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

Aby przesłać zapytanie dotyczące asynchronicznego raportu o zarabianiu, wyślij żądanie POST na adres /mint/organizations/org_id/async-reports.

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

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

W treści żądania określ te kryteria wyszukiwania:

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

Na przykład to żądanie generuje asynchroniczny raport o zarabianiu za czerwiec 2017 r. dla określonego 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