Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje
Apigee Edge rejestruje różnorodne dane operacyjne i biznesowe, które przepływają przez interfejsy API. Wskaźniki uzyskane na podstawie tych danych przydają się do monitorowania operacyjnego i monitorowania działalności. Za pomocą Edge API Analytics możesz na przykład określić, które interfejsy API działają dobrze, a które słabo, którzy deweloperzy generują ruch o największej wartości i które aplikacje powodują najwięcej problemów z usługami backendu.
Aby ułatwić dostęp do tych wskaźników, Edge udostępnia interfejs API typu REST. Interfejsu API wskaźników możesz używać, gdy chcesz zautomatyzować niektóre funkcje Analytics, np. okresowo pobierać dane za pomocą klienta lub skryptu automatyzacji. Za pomocą interfejsu API możesz też tworzyć własne wizualizacje w postaci niestandardowych widżetów, które możesz umieścić w portalach lub aplikacjach niestandardowych.
Aby dowiedzieć się, jak korzystać z Analytics w interfejsie zarządzania Edge API, przeczytaj omówienie interfejsu API Analytics.
Interfejsy API wskaźników
Edge udostępnia 2 interfejsy API wskaźników:
Funkcja Pobierz wskaźniki zwraca wskaźniki dotyczące organizacji i środowiska z pewnego okresu, na przykład z godziny, dnia lub tygodnia.
Na przykład za poprzedni tydzień chcesz uzyskać:
- Liczba błędów związanych z naruszeniem zasad
- Średni czas odpowiedzi
- Łączny ruch
Porządkowanie danych według wymiarów zwraca dane z określonego przedziału czasu dotyczące organizacji i środowiska pogrupowane według wymiaru.
W zeszłym tygodniu za pomocą wymiarów możesz np. grupować dane według usługi API, serwera proxy interfejsu API i adresu e-mail dewelopera, aby uzyskać:
- liczbę błędów związanych z naruszeniem zasad w poszczególnych usługach API,
- Średni czas odpowiedzi na serwer proxy interfejsu API
- Łączny ruch z adresu e-mail dewelopera
Interfejs API uporządkowania danych według wymiarów obsługuje dodatkowe funkcje, których nie obsługuje korzystanie z danych, m.in.:
Informacje o limitach interfejsu Metrics API
Edge wymusza następujące limity dla tych wywołań. Limit zależy od systemu backendu, który obsługuje wywołanie:
- Postgres: 40 połączeń na minutę
- BigQuery 12 połączeń na minutę
Wskaż system backendu, który obsługuje wywołanie, sprawdzając obiekt odpowiedzi.
Każdy obiekt odpowiedzi zawiera właściwość metaData, która zawiera listę usługi, która obsługiwała wywołanie we właściwości Source. Na przykład w 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ń, API zwróci odpowiedź HTTP 429.
Uzyskiwanie wskaźników za pomocą interfejsu API zarządzania
Główna różnica między tymi 2 interfejsami API polega na tym, że funkcja Pobierz dane zwraca nieprzetworzone dane dla całej organizacji i środowiska, a porządkowanie danych według wymiarów umożliwia grupowanie danych według różnych typów encji, takich jak produkt API, deweloper i aplikacja.
Adres URL żądania interfejsu API Get wskaźników to:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats
W przypadku uporządkowania danych według wymiarów
do adresu URL po elemencie /stats należy dołączyć dodatkowy zasób określającywymiar:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension
Aby na przykład uzyskać wskaźniki pogrupowane według serwera 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/apiproxy
Określanie danych do zwrócenia
W przypadku interfejsów API pobierania danych i uporządkowania danych według wymiarów parametr zapytania select służy do określenia metrics do pobrania oraz opcjonalnej funkcji agregacji w formie:
?select=metric
lub
?select=aggFunction(metric)
Gdzie:
- Argument dane 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 zasad. W sekcji metrics znajdziesz tabelę, która określa nazwę danych używaną z parametrem zapytania
select. aggFunction określa opcjonalną funkcję agregacji uruchomioną na podstawie wskaźnika. Możesz na przykład użyć następujących funkcji agregacji ze wskaźnikiem czasu oczekiwania na przetwarzanie:
avg: zwraca średni czas oczekiwania na przetwarzanie.min: zwraca minimalny czas oczekiwania na przetwarzanie.max: zwraca maksymalny czas oczekiwania na przetwarzanie.-
sum: zwraca sumę wszystkich opóźnień przetwarzania.
Nie wszystkie wskaźniki obsługują wszystkie funkcje agregacji. Dokumentacja metrics zawiera tabelę, która określa nazwę danych i funkcję (
sum,avg,min,max) obsługiwane przez ten rodzaj danych.
Aby na przykład zwrócić średnią liczbę transakcji, czyli żądań serwera proxy interfejsu API, na sekundę:
?select=tps
Zwróć uwagę, że ten przykład nie wymaga funkcji agregacji. W następnym przykładzie do zwrócenia sumy działań z pamięci podręcznej użyto funkcji agregacji:
?select=sum(cache_hit)
Możesz zwrócić wiele wskaźników dla jednego wywołania interfejsu API. Aby uzyskać wskaźniki sumy błędów związanych z zasadami i średniego rozmiaru żądania, ustaw parametr zapytania select za pomocą listy wskaźników rozdzielonych przecinkami:
?select=sum(policy_error),avg(request_size)
Określanie przedziału czasu
Interfejs Metric API zwraca dane z wybranego okresu. Aby określić przedział czasu, użyj parametru zapytania timeRange w formacie:
?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 +, jak w tym przykładzie: 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 jako godziny, ponieważ kończy się ona około 00:00. Zamiast niego użyj formatu 23:59.
Używanie separatora
Aby rozdzielić kilka wymiarów w wywołaniu interfejsu API, jako separatora użyj przecinka (,).
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 znakiem ,.
Przykładowe wywołania interfejsu API
Ta sekcja zawiera przykłady korzystania z interfejsów API pobierania danych i uporządkowania wskaźników według wymiarów. Więcej przykładów znajdziesz w sekcji Przykłady interfejsu Metrics API.
Zwraca łączną liczbę wywołań interfejsów API w ciągu miesiąca
Aby wyświetlić łączną liczbę wywołań wszystkich interfejsów API w Twojej organizacji i środowisku w ciągu jednego miesiąca, użyj interfejsu API Pobierz wskaźniki:
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"
}
],
...
}
Zwracaj łączną liczbę wiadomości dla każdego serwera proxy interfejsu API przez 2 dni
W tym przykładzie zwracasz wskaźniki liczby żądań otrzymanych przez wszystkie serwery 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 z żądaniami dla wszystkich interfejsów API dla ruchu otrzymanego od początku 20 czerwca 2018 r. do końca 21 czerwca 2018 r. (czas 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ź oznacza, że między początkiem 20 czerwca 2018 r. a końcem 21 czerwca 2018 r. w środowisku testowym odebrano komunikat 1100 wiadomości przez jeden serwer proxy interfejsu API o nazwie „target-reroute”.
Aby uzyskać dane dla innych wymiarów, jako parametr URI wybierz inny wymiar. Możesz np. określić wymiar developer_app, aby pobierać dane o aplikacjach dla deweloperów. To wywołanie interfejsu API zwraca łączną przepustowość (odebrane 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:password
Przykł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 rankingu względnego
Często podczas pobierania wskaźników chcesz uzyskać wyniki tylko dla podzbioru wszystkich danych. Zwykle trzeba znaleźć wyniki dla „10 najpopularniejszych aplikacji”, np. „10 najwolniejszych interfejsów API” czy „10 najbardziej aktywnych aplikacji”. Możesz to zrobić, używając w żądaniu parametru zapytania topk.
Na przykład możesz chcieć się dowiedzieć, kim są Twoi najlepsi programiści (pod względem przepustowości) lub najgorsi (np. „najwolniejsze najwolniejsze”) docelowe interfejsy API są określane na podstawie czasu oczekiwania.
Element topk (oznaczający „górne k”) umożliwia raportowanie elementów powiązanych z najwyższą wartością danego rodzaju danych. Dzięki temu możesz filtrować wskaźniki dla listy encji, które ilustrują konkretny warunek. Aby np. dowiedzieć się, który docelowy adres URL był najbardziej podatny na błędy w ciągu ostatniego tygodnia, do żądania jest dołączany 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 zbiór wskaźników, które wskazują, że najbardziej nieprawidłowy 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 wskaźniki z najwyżej ocenianego interfejsu API, zdefiniowane przez największą przepustowość w ciągu ostatniego tygodnia:
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ć liczbę zwracanych danych. Jeśli używasz 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 na usługę backendu. Aby to zrobić, użyj wymiaru target_url w połączeniu 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"
}
]...
}
Podział wyników na strony
W środowiskach produkcyjnych niektóre żądania wysyłane 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 użytkownika, interfejs API natywnie obsługuje podział na strony.
Do podziału wyników na strony używaj parametrów zapytania offset i limit razem z parametrem sortowania sortby, aby zapewnić spójną kolejność elementów.
Na przykład poniższe żądanie prawdopodobnie zwróci duży zbiór danych, ponieważ pobiera wskaźniki dotyczące wszystkich błędów we wszystkich interfejsach API w środowisku usługi z 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 Twoja aplikacja oparta na interfejsie użytkownika może wyświetlać 50 wyników na stronę, możesz ustawić ten limit na 50. Wartość 0 jest liczona jako pierwszy element, więc następne wywołanie zwraca elementy od 0 do 49 w kolejności malejącej (wartość domyślna to sort=DESC).
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 przesunięcia w podany niżej sposób. Pamiętaj, że limit i przesunięcie są identyczne. Dzieje się tak, ponieważ jako pierwszy element liczy się 0. Przy limicie wynoszącym 50 i przesunięciu równym 0 zwracane są elementy z zakresu od 0 do 49. Przy przesunięciu równą 50 zwracane są elementy z zakresu od 50 do 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