Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację
Apigee X. info
Apigee Edge rejestruje wiele danych operacyjnych i firmowych baz danych, które przepływają przez interfejsy API. Dane pochodzące z tych danych są przydatne do monitorowania operacyjnego i biznesowego. Korzystając z dodatku Edge API Analytics, możesz na przykład określić, które interfejsy API działają dobrze lub źle, którzy deweloperzy generują ruch o największej wartości oraz które aplikacje powodują najwięcej problemów z usługami backendu.
Aby ułatwić dostęp do tych danych, Edge udostępnia interfejs RESTful API. Możesz używać interfejsu Metrics API, gdy chcesz zautomatyzować niektóre funkcje Analytics, np. okresowe pobieranie danych za pomocą klienta lub skryptu automatyzacji. Możesz też używać interfejsu API do tworzenia własnych wizualizacji w postaci niestandardowych widżetów, które możesz umieszczać w portalach lub aplikacjach niestandardowych.
Aby dowiedzieć się, jak korzystać z Analytics w interfejsie zarządzania API Edge, przeczytaj artykuł Omówienie API Analytics.
Informacje o interfejsach Metrics API
Edge udostępnia 2 interfejsy Metrics API:
Get metrics zwraca dane dotyczące organizacji i środowiska w określonym przedziale czasu, np. w ciągu godziny, dnia lub tygodnia.
Na przykład w przypadku poprzedniego tygodnia chcesz uzyskać:
- liczbę błędów dotyczących zasad,
- średni czas odpowiedzi,
- całkowity ruch.
Get metrics organized by dimensions zwraca dane z określonego przedziału czasu dotyczące organizacji i środowiska zgrupowane według wymiaru.
Na przykład w przypadku poprzedniego tygodnia używasz wymiarów do grupowania danych według produktu API, proxy interfejsu API, i adresu e-mail dewelopera, aby uzyskać:
- liczbę błędów dotyczących zasad na produkt API,
- średni czas odpowiedzi na proxy interfejsu API,
- całkowity ruch na adres e-mail dewelopera.
Interfejs Get metrics organized by dimensions API obsługuje dodatkowe funkcje, które nie są obsługiwane przez interfejs Get metrics API, w tym:
Limity interfejsów Metrics API
Edge nakłada te limity na te wywołania. Limit jest oparty na systemie backendu, który obsługuje wywołanie:
- Postgres: 40 wywołań na minutę
- BigQuery: 12 wywołań na minutę
Aby określić system backendu, który obsługuje wywołanie, sprawdź obiekt odpowiedzi.
Każdy obiekt odpowiedzi zawiera właściwość metaData, która zawiera usługę obsługującą wywołanie
we właściwości Source. Na przykład w przypadku Postgres:
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}W przypadku BigQuery właściwość Source to:
"Source:Big Query"
Jeśli przekroczysz limit wywołań, interfejs API zwróci odpowiedź HTTP 429.
Pobieranie danych za pomocą interfejsu Management API
Główna różnica między tymi 2 interfejsami polega na tym, że interfejs Get metrics zwraca surowe dane dotyczące całej organizacji i środowiska, a interfejs Get metrics organized by dimensions umożliwia grupowanie danych według różnych typów encji, takich jak produkt API, deweloper i aplikacja.
Adres URL żądania interfejsu Get metrics API to:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/statsW przypadku interfejsu Get metrics organized by dimensions
API dołączasz do adresu URL po /stats dodatkowy zasób, który określa żądany wymiar:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimensionAby na przykład pobrać dane pogrupowane według proxy interfejsu API, użyj tego adresu URL do wywołania interfejsu Management API:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxyOkreślanie danych do zwrócenia
W przypadku interfejsów
Get metrics i
Get metrics organized by dimensions
API używasz parametru zapytania select, aby określić dane
do pobrania, oraz opcjonalnej funkcji agregacji w postaci:
?select=metric
lub
?select=aggFunction(metric)
Gdzie:
- metric określa dane, które chcesz zwrócić. Na przykład,
liczba żądań do interfejsu API, trafień w pamięci podręcznej lub błędów dotyczących zasad. Więcej informacji znajdziesz w tabeli danych
, która określa nazwę danych do użycia z parametrem zapytania
select. aggFunction określa opcjonalną funkcję agregacji uruchamianą na podstawie danych. Na przykład w przypadku danych dotyczących opóźnienia przetwarzania możesz użyć tych funkcji agregacji:
avg: zwraca średnie opóźnienie przetwarzania.min: zwraca minimalne opóźnienie przetwarzania.max: zwraca maksymalne opóźnienie przetwarzania.-
sum: zwraca sumę wszystkich opóźnień przetwarzania.
Nie wszystkie dane obsługują wszystkie funkcje agregacji. Dokumentacja dotycząca danych zawiera tabelę, która określa nazwę danych i funkcję (
sum,avg,min,max) obsługiwaną przez dane.
Aby na przykład zwrócić średnią liczbę transakcji, czyli żądań proxy interfejsu API, na sekundę:
?select=tps
Zwróć uwagę, że ten przykład nie wymaga funkcji agregacji. Następny przykład używa funkcji agregacji do zwrócenia sumy trafień w pamięci podręcznej:
?select=sum(cache_hit)
W przypadku jednego wywołania interfejsu API możesz zwrócić wiele danych. Aby uzyskać dane dotyczące sumy błędów dotyczących zasad
i średniego rozmiaru żądania, ustaw parametr zapytania select za pomocą rozdzielonej przecinkami
listy danych:
?select=sum(policy_error),avg(request_size)
Określanie przedziału czasu
Interfejs Metrics API zwraca dane z określonego przedziału czasu. Aby określić przedział czasu, użyj parametru zapytania timeRange
w postaci:
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
Zwróć uwagę na %20 przed HH:MM. Parametr timeRange wymaga znaku spacji zakodowanego w adresie URL przed HH:MM lub znaku +, np. MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.
Na przykład:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
Nie używaj godziny 24:00, ponieważ jest ona traktowana jako 00:00. Zamiast tego użyj godziny 23:59.
Używanie separatora
Aby rozdzielić wiele wymiarów w wywołaniu interfejsu API, użyj przecinka (,) jako separatora.
Na przykład w wywołaniu interfejsu API
curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
wymiary apis i apps są rozdzielone przez ,.
Przykładowe wywołania interfejsu API
Ta sekcja zawiera przykłady użycia interfejsów Get metrics i Get metrics organized by dimensions API. Dodatkowe przykłady znajdziesz w artykule Przykłady interfejsu Metrics API.
Zwracanie łącznej liczby wywołań interfejsów API w ciągu miesiąca
Aby sprawdzić łączną liczbę wywołań wszystkich interfejsów API w organizacji i środowisku w ciągu miesiąca, użyj interfejsu Get metrics API:
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
Przykładowa odpowiedź:
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}Zwracanie łącznej liczby wiadomości na proxy interfejsu API w ciągu 2 dni
W tym przykładzie zwracasz dane dotyczące liczby żądań otrzymanych przez wszystkie proxy interfejsu API
w ciągu 2 dni. Parametr zapytania select definiuje funkcję agregacji sum dla danych
message_count w wymiarze apiproxy. Raport zwraca przepustowość wiadomości żądań
dla wszystkich interfejsów API w przypadku ruchu otrzymanego między początkiem 20 czerwca 2018 r. a końcem 21 czerwca 2018 r. w
czasie UTC:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
Przykładowa odpowiedź:
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1498003200000,
"value" : "1100.0"
} ]
} ],
"name" : "target-reroute"
} ],
"name" : "test"
} ]...
}Ta odpowiedź wskazuje, że między początkiem 20 czerwca 2018 r. a końcem 21 czerwca 2018 r. jedno proxy interfejsu API o nazwie „target-reroute” działające w środowisku testowym otrzymało 1100 wiadomości.
Aby uzyskać dane dotyczące innych wymiarów, określ inny wymiar jako parametr URI. Możesz na
przykład określić wymiar developer_app, aby pobrać dane dotyczące
aplikacji dewelopera. To wywołanie interfejsu API zwraca łączną przepustowość (otrzymane wiadomości) ze wszystkich aplikacji
w określonym przedziale czasu:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:passwordPrzykładowa odpowiedź:
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "886.0"
}
]
}
],
"name": "Test-App"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "6645.0"
}
]
}
],
"name": "johndoe_app"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "1109.0"
}
]
}
],
"name": "marys_app"
}
]...
}Sortowanie wyników według względnej pozycji
W wielu przypadkach podczas pobierania danych chcesz uzyskać wyniki tylko dla podzbioru całego zbioru danych. Zwykle musisz uzyskać wyniki dla „10 najlepszych”, np. „10 najwolniejszych
interfejsów API” lub „10 najbardziej aktywnych aplikacji”. Możesz to zrobić za pomocą parametru zapytania topk
w ramach żądania.
Możesz na przykład sprawdzić, którzy deweloperzy są najlepsi pod względem przepustowości, lub które interfejsy API docelowe o najgorszej wydajności (czyli „najwolniejsze”) mają największe opóźnienie. „Najwolniejsze” interfejsy API docelowe mają największe opóźnienie.
Parametr topk (czyli „k najlepszych” encji) umożliwia raportowanie encji powiązanych
z najwyższą wartością danego wskaźnika. Umożliwia to filtrowanie danych pod kątem listy
encji, które ilustrują określony warunek. Aby na przykład sprawdzić, który docelowy adres URL był najbardziej podatny na błędy w ciągu ostatniego tygodnia, do żądania dodaj parametr topk z wartością 1:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
-u email:password
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(is_error)",
"values": [
{
"timestamp": 1494201600000,
"value": "12077.0"
}
]
}
],
"name": "http://api.company.com"
}
]...
}Wynikiem tego żądania jest zestaw danych, który pokazuje, że najbardziej podatny na błędy docelowy adres URL to
http://api.company.com.
Możesz też użyć parametru topk, aby posortować interfejsy API o największej
przepustowości. Ten przykład pobiera dane dotyczące interfejsu API o najwyższej pozycji, określonej przez największą
przepustowość w ostatnim tygodniu:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password
Przykładowa odpowiedź
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1494720000000,
"value": "5750.0"
},
{
"timestamp": 1494633600000,
"value": "5752.0"
},
{
"timestamp": 1494547200000,
"value": "5747.0"
},
{
"timestamp": 1494460800000,
"value": "5751.0"
},
{
"timestamp": 1494374400000,
"value": "5753.0"
},
{
"timestamp": 1494288000000,
"value": "5751.0"
},
{
"timestamp": 1494201600000,
"value": "5752.0"
}
]
}
],
"name": "testCache"
}
],
"name": "test"
}
]...
}Filtrowanie wyników
Aby uzyskać większą szczegółowość, możesz filtrować wyniki, aby ograniczyć zwracane dane. Podczas korzystania z filtrów musisz używać wymiarów jako właściwości filtra.
Załóżmy na przykład, że musisz pobrać liczbę błędów z usług backendu
filtrowanych według czasownika HTTP żądania. Twoim celem jest sprawdzenie, ile żądań POST i PUT
generuje błędy w każdej usłudze backendu. Aby to zrobić, użyj wymiaru
target_url wraz z filtrem request_verb:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password
Przykładowa odpowiedź:
{
"environments" : [
{
"dimensions" : [
{
"metrics" : [
{
"name" : "sum(is_error)",
"values" : [
{
"timestamp" : 1519516800000,
"value" : "1.0"
}
]
}
],
"name" : "testCache"
}
],
"name" : "test"
}
]...
}Stronicowanie wyników
W środowiskach produkcyjnych niektóre żądania do interfejsu Edge Analytics API zwracają bardzo duże zbiory danych. Aby ułatwić wyświetlanie dużych zbiorów danych w kontekście aplikacji opartej na interfejsie, interfejs API natywnie obsługuje stronicowanie.
Aby stronicować wyniki, użyj parametrów zapytania offset i limit,
wraz z parametrem sortowania sortby, aby zapewnić spójną kolejność
elementów.
Na przykład to żądanie prawdopodobnie zwróci duży zbiór danych, ponieważ pobiera dane dotyczące wszystkich błędów we wszystkich interfejsach API w środowisku produkcyjnym w ciągu ostatniego tygodnia.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
Jeśli aplikacja oparta na interfejsie może wyświetlać 50 wyników na stronie, możesz ustawić limit
na 50. Ponieważ 0 jest traktowane jako pierwszy element, to wywołanie zwraca elementy 0–49 w kolejności malejącej (sort=DESC jest wartością domyślną).
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password
W przypadku drugiej „strony” wyników użyj parametru zapytania offset w ten sposób. Zwróć uwagę, że limit i przesunięcie są identyczne. Dzieje się tak, ponieważ 0 jest traktowane jako pierwszy element. Przy limicie 50 i przesunięciu 0 zwracane są elementy 0–49. Przy przesunięciu 50 zwracane są elementy 50–99.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password