INTEGRITY Dokumentace

← Analytics / analytics / graphql-api / migration-guides

Zone Analytics Colos Endpoint na GraphQL Analytics

Tento průvodce ukazuje, jak přejít ze zastaralého rozhraní zone analytics API (jehož podpora bude brzy ukončena) na rozhraní GraphQL API. Uvádí příklad reálného případu použití koncového bodu colos a poté ukazuje, jak tento případ použití převést do podoby dotazu na GraphQL API. Zabývá se také funkcemi rozhraní GraphQL API, díky nimž je výkonnější než rozhraní, které nahrazuje.

V tomto příkladu chceme spočítat počet požadavků pro konkrétní colo, rozdělený podle hodiny, ve které požadavky proběhly. S využitím koncového bodu colos v analytice zóny můžeme sestavit příkaz curl, který data z API načte.

curl -H "Authorization: Bearer $API_TOKEN" "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/analytics/colos?since=2020-12-10T00:00:00Z"  > colos_endpoint_output.json

Tento dotaz říká:

Otázka, na kterou chceme odpovědět, zní: „Kolik požadavků na ZHR připadá na hodinu?“ Pomocí dat z odpovědi koncového bodu colos a drobné úpravy nástrojem jq můžeme na tuto otázku odpovědět tímto příkazem:

cat colos_endpoint_output.json | jq  -c '.result[] | {colo_id: .colo_id, timeseries: .timeseries[]} | {colo_id: .colo_id, timeslot: .timeseries.since, requests: .timeseries.requests.all, bandwidth: .timeseries.bandwidth.all} | select(.requests > 0) | select(.colo_id == "ZRH") '

Tento příkaz jq je složitý, proto si ho rozebereme:

.result[]

To znamená, že se pole výsledků rozdělí na jednotlivé řádky JSON.

{colo_id: .colo_id, timeseries: .timeseries[]}

Tím se každý řádek JSON rozdělí na více řádků JSON. Každý výsledný řádek obsahuje colo_id a jeden prvek z timeseries pole.

{colo_id: .colo_id, timeslot: .timeseries.since, requests: .timeseries.requests.all, bandwidth: .timeseries.bandwidth.all}

Tím se zploští data, o která máme zájem a která se nacházejí uvnitř objektu timeseries každého řádku.

select(.requests > 0) | select(.colo_id == "ZRH")

Tím se vyberou pouze řádky, které obsahují více než 0 požadavků a colo_id je ZRH.

Výsledná data, která získáme, vypadají jako následující odpověď:

Odpověď

{"colo_id":"ZRH","timeslot":"2020-12-10T00:00:00Z","requests":601,"bandwidth":683581}
{"colo_id":"ZRH","timeslot":"2020-12-10T01:00:00Z","requests":484,"bandwidth":550936}
{"colo_id":"ZRH","timeslot":"2020-12-10T02:00:00Z","requests":326,"bandwidth":370627}
{"colo_id":"ZRH","timeslot":"2020-12-10T03:00:00Z","requests":354,"bandwidth":402527}
{"colo_id":"ZRH","timeslot":"2020-12-10T04:00:00Z","requests":446,"bandwidth":507234}
{"colo_id":"ZRH","timeslot":"2020-12-10T05:00:00Z","requests":692,"bandwidth":787688}
{"colo_id":"ZRH","timeslot":"2020-12-10T06:00:00Z","requests":1474,"bandwidth":1676166}
{"colo_id":"ZRH","timeslot":"2020-12-10T07:00:00Z","requests":2839,"bandwidth":3226871}
{"colo_id":"ZRH","timeslot":"2020-12-10T08:00:00Z","requests":2953,"bandwidth":3358487}
{"colo_id":"ZRH","timeslot":"2020-12-10T09:00:00Z","requests":2550,"bandwidth":2901823}
{"colo_id":"ZRH","timeslot":"2020-12-10T10:00:00Z","requests":2203,"bandwidth":2504615}
...

Jak dosáhneme stejného výsledku pomocí GraphQL API?

GraphQL API nám umožňuje mnohem přesněji určit, jaká data chceme získat. Zatímco koncový bod colos nás nutí načíst všechny informace o rozdělení požadavků a šířky pásma podle jednotlivých colo, GraphQL API nám umožňuje získat pouze ty informace, které nás zajímají.

Potřebujeme data o HTTP požadavcích, proto použijeme kanonický zdroj těchto dat, známý také jako httpRequestsAdaptiveGroups. Tento uzel v GraphQL API umožňuje filtrovat a seskupovat podle prakticky jakékoli myslitelné dimenze HTTP požadavku. Je Adaptivní takže odpovědi budou rychlé, protože je pohání naše Technologie ABR ↗.

Následuje dotaz GraphQL API, kterým získáme data potřebná k zodpovězení otázky: „Kolik požadavků na ZHR připadá na hodinu?“

{
  viewer {
    zones(filter: {zoneTag:"$ZONE_TAG"}) {
      httpRequestsAdaptiveGroups(filter: {datetime_gt: "2020-12-10T00:00:00Z", coloCode:"ZRH"}, limit:10000, orderBy: [datetimeHour_ASC]) {
        count
        sum {
          edgeResponseBytes
        }
        avg {
          sampleInterval
        }
        count
        dimensions {
          datetimeHour
          coloCode
        }
      }
    }
  }
}

Poté ho můžeme spustit pomocí curl:

curl -X POST -H "Authorization: Bearer $API_TOKEN"  https://api.cloudflare.com/client/v4/graphql -d "@./coloGroups.json" > graphqlColoGroupsResponse.json

Na naši otázku můžeme odpovědět stejným způsobem jako dříve, a to pomocí jq:

cat graphqlColoGroupsResponse.json| jq -c '.data.viewer.zones[] | .httpRequestsAdaptiveGroups[] | {colo_id: .dimensions.coloCode, timeslot: .dimensions.datetimeHour, requests: .count, bandwidth: .sum.edgeResponseBytes}'

Tento příkaz je mnohem jednodušší než ten předchozí, protože data vrácená rozhraním GraphQL API jsou konkrétnější než data vrácená koncovým bodem colos.

Přesto stojí za to si příkaz vysvětlit, protože pomůže pochopit některé koncepty, na kterých GraphQL API stojí.

.data.viewer.zones[]

Formát odpovědi GraphQL je velmi podobný dotazu. Úspěšná odpověď vždy obsahuje data objekt, který data v odpovědi obaluje. Dotaz vždy obsahuje viewer objekt, který představuje vašeho uživatele. Poté rozbalíme objekty zón, jeden na řádek. Náš dotaz obsahuje pouze jednu zónu, protože jsme si to tak zvolili. Dotaz by ale mohl obsahovat i více zón.

.httpRequestsAdaptiveGroups[]

httpRequestsAdaptiveGroups pole je seznam, kde každý datový bod v seznamu představuje kombinaci vybraných dimenzí spolu s agregací zvolenou pro danou kombinaci dimenzí. Zde jednotlivé datové body rozbalíme, jeden na řádek.

{colo_id: .dimensions.coloCode, timeslot: .dimensions.datetimeHour, requests: .count, bandwidth: .sum.edgeResponseBytes}

Je to jednoduché: pouze vybere atributy jednotlivých datových bodů, o které máme zájem, ve formátu, který jsme dříve používali u koncového bodu colos.

GraphQL API je velmi silný nástroj, protože data můžete filtrovat a seskupovat podle mnoha dimenzí. Tuto funkci koncový bod colos v Zone Analytics API vůbec nenabízí.