Metrik API'lerini kullanma

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Apigee Edge, API'ler üzerinden gelen çeşitli operasyonel verilere ve işletme verilerine erişim sunar. Bu verilerden elde edilen metrikler, operasyonel izleme ve işletme izleme için faydalıdır. Örneğin, Edge API Analytics'i kullanarak hangi API'lerin iyi veya kötü performans gösterdiğini, hangi geliştiricilerin en yüksek değerli trafiği sağladığını ve hangi uygulamaların arka uç hizmetlerinizde en çok soruna neden olduğunu belirleyebilirsiniz.

Edge, bu metrik verilerine kolayca erişebilmeniz için bir RESTful API sunar. Otomasyon istemcisi veya komut dosyası kullanarak metrikleri düzenli olarak alma gibi belirli Analytics işlevlerini otomatikleştirmeniz gerektiğinde Metrics API'yi kullanabilirsiniz. API'yi, portallara veya özel uygulamalara yerleştirebileceğiniz özel widget'lar şeklinde kendi görselleştirmelerinizi oluşturmak için de kullanabilirsiniz.

Analytics'i API Edge yönetim kullanıcı arayüzünde kullanma hakkında bilgi edinmek için API Analytics'e genel bakış başlıklı makaleyi inceleyin.

Metriklerle ilgili API'ler hakkında

Edge, iki metrik API'si sağlar:

  • Get metrics bir kuruluş ve ortam için bir saat, gün veya hafta gibi bir süre boyunca metrikler döndürür.

    Örneğin, önceki haftaya ait aşağıdaki bilgileri almak istiyorsunuz:

    • Politika hatalarının sayısı
    • Ortalama yanıtlama süresi
    • Toplam trafik

  • Boyutlara göre düzenlenmiş metrikleri alma bir kuruluş ve ortam için belirli bir dönemdeki metrikleri boyuta göre gruplandırılmış olarak döndürür.

    Örneğin, önceki hafta için aşağıdaki bilgileri elde etmek üzere metrikleri API ürünü, API proxy'si ve geliştirici e-posta adresine göre gruplandırmak için boyutları kullanırsınız:

    • API ürünü başına politika hatası sayısı
    • API proxy'si başına ortalama yanıtlama süresi
    • Geliştirici e-postası başına toplam trafik

    Get metrics organized by dimensions API, Get metrics API'nin desteklemediği ek özellikleri destekler. Örneğin:

Metriklerle ilgili API kotaları hakkında

Edge, bu çağrılarda aşağıdaki kotaları uygular. Kota, aramayı işleyen arka uç sistemine göre belirlenir:

  • Postgres: Dakikada 40 çağrı
  • BigQuery: Dakikada 12 çağrı

Yanıt nesnesini inceleyerek çağrıyı işleyen arka uç sistemini belirleyin. Her yanıt nesnesi, Source özelliğinde çağrıyı işleyen hizmeti listeleyen bir metaData özelliği içerir. Örneğin, Postgres için:

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

BigQuery için Source özelliği şöyledir: 

"Source:Big Query"

Çağrı kotasını aşarsanız API, HTTP 429 yanıtı döndürür.

Yönetim API'si ile metrikleri alma

İki API arasındaki temel fark, Get metrics'in kuruluşun ve ortamın tamamı için ham metrikler döndürmesi, Get metrics organized by dimensions'ın ise metrikleri API ürünü, geliştirici ve uygulama gibi farklı öğe türlerine göre gruplandırmanıza olanak tanımasıdır.

Get metrics API'sinin istek URL'si şöyledir:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

Get metrics organized by dimensions API'sinde, /stats işaretinden sonra URL'ye istenen boyutu belirten ek bir kaynak eklersiniz:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

Örneğin, API proxy'sine göre gruplandırılmış metrikleri almak için yönetim API'sini çağırmak üzere aşağıdaki URL'yi kullanırsınız:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

Döndürülecek metrikleri belirtme

Hem Get metrics hem de Get metrics organized by dimensions API'lerinde, alınacak metrikleri ve isteğe bağlı bir toplama işlevini belirtmek için select sorgu parametresini şu biçimde kullanırsınız:

?select=metric

veya:

?select=aggFunction(metric)

Burada:

  • metric, döndürmek istediğiniz verileri belirtir. Örneğin, API isteklerinin, önbellek isabetlerinin veya politika hatalarının sayısı. select sorgu parametresiyle kullanılacak metrik adını belirten bir tablo için metriklere bakın.

  • aggFunction, metriğe karşı çalıştırılan isteğe bağlı toplama işlevini belirtir. Örneğin, işlem gecikmesi metriğiyle aşağıdaki toplama işlevlerini kullanabilirsiniz:

    • avg: Ortalama işleme gecikmesini döndürür.
    • min: Minimum işleme gecikmesini döndürür.
    • max: Maksimum işleme gecikmesini döndürür.
    • sum: Tüm işleme gecikmelerinin toplamını döndürür.

    Tüm metrikler, tüm toplama işlevlerini desteklemez. Metriklerle ilgili dokümanlarda, metrik adını ve metrik tarafından desteklenen işlevi (sum, avg, min, max) belirten bir tablo yer alır.

Örneğin, saniye başına ortalama işlem sayısını (API proxy istekleri) döndürmek için: 

?select=tps

Bu örnekte toplama işlevinin gerekmediğini unutmayın. Aşağıdaki örnekte, önbellek isabetlerinin toplamını döndürmek için bir toplama işlevi kullanılmaktadır:

?select=sum(cache_hit)

Tek bir API çağrısı için birden fazla metrik döndürebilirsiniz. Politika hatalarının toplamı ve ortalama istek boyutuyla ilgili metrikleri almak için select sorgu parametresini virgülle ayrılmış bir metrik listesi kullanarak ayarlayın:

?select=sum(policy_error),avg(request_size)

Zaman aralığını belirtme

Metrics API, belirli bir dönemdeki verileri döndürür. Dönemi belirtmek için timeRange sorgu parametresini şu biçimde kullanın:

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

HH:MM tarihinden önce %20 tarihine dikkat edin. timeRange parametresi, HH:MM karakterinden önce URL kodlu bir boşluk karakteri veya + karakteri gerektirir. Örneğin: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Örneğin:

?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

24:00, 00:00'a yuvarlandığı için saat olarak kullanılmamalıdır. Bunun yerine 23:59'u kullanın.

Ayırıcı kullanma

Bir API çağrısında birden fazla boyutu ayırmak için sınırlayıcı olarak virgül (,) kullanın. Örneğin, API çağrısında

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

apis ve apps boyutları , ile ayrılır.

Örnek API çağrıları

Bu bölümde, Get metrics ve Get metrics organized by dimensions API'lerinin kullanıldığı örnekler yer almaktadır. Ek örnekler için Metrics API örnekleri bölümüne bakın.

API'lerinize bir ay boyunca yapılan toplam çağrı sayısını döndürün

Bir ay boyunca kuruluşunuzdaki ve ortamınızdaki tüm API'lere yapılan toplam çağrı sayısını görmek için Get metrics API'sini kullanın:

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

Örnek Yanıt:

{
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

İki gün boyunca API proxy'si başına toplam ileti sayısını döndürün

Bu örnekte, iki günlük bir süre boyunca tüm API proxy'leri tarafından alınan istek sayısıyla ilgili metrikleri döndürüyorsunuz. select sorgu parametresi, apiproxy boyutundaki message_count metriği için sum toplama işlevini tanımlar. Rapor, 20.06.2018'in başından 21.06.2018'in sonuna kadar alınan trafik için tüm API'lerin istek mesajı işleme hızını UTC saatine göre döndürür:

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

Örnek Yanıt:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

Bu yanıt, 20.06.2018'in başlangıcı ile 21.06.2018'in sonu arasında test ortamında çalışan "target-reroute" adlı bir API proxy'si tarafından 1.100 mesaj alındığını gösteriyor.

Diğer boyutlarla ilgili metrikleri almak için URI parametresi olarak farklı bir boyut belirtin. Örneğin, geliştirici uygulamalarıyla ilgili metrikleri almak için developer_app boyutunu belirtebilirsiniz. Aşağıdaki API çağrısı, belirtilen zaman aralığında herhangi bir uygulamadan alınan toplam işleme hızını (alınan mesajlar) döndürür:

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

Örnek Yanıt:

{
  "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"
        }
  ]...
}

Sonuçları göreceli sıralamaya göre sıralama

Metrikleri alırken çoğu zaman yalnızca toplam veri kümesinin bir alt kümesiyle ilgili sonuçları almak istersiniz. Genellikle, "en yavaş 10 API", "en etkin 10 uygulama" gibi "ilk 10" sonuçlarını almanız gerekir. Bunu, isteğin bir parçası olarak topk sorgu parametresini kullanarak yapabilirsiniz.

Örneğin, verimliliğe göre en iyi geliştiricilerinizin kimler olduğunu veya en kötü performans gösterenlerin (ör. "En yavaş") hedef API'ler gecikmeye göre sıralanır.

topk (yani "en iyi k" öğeleri), belirli bir metrik için en yüksek değere sahip öğelerle ilişkili raporlamayı sağlar. Bu sayede, belirli bir koşulu örnekleyen bir varlık listesi için metrikleri filtreleyebilirsiniz. Örneğin, geçen hafta en çok hataya neden olan hedef URL'yi bulmak için isteğe topk parametresi eklenir ve bu parametrenin değeri 1 olur:

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"
        }
      ]...
}

Bu isteğin sonucu, en çok hata içeren hedef URL'nin http://api.company.com olduğunu gösteren bir metrik grubudur.

En yüksek işleme hızına sahip API'leri sıralamak için topk parametresini de kullanabilirsiniz. Aşağıdaki örnek, geçen hafta en yüksek işleme hızıyla tanımlanan ve en üst sırada yer alan API ile ilgili metrikleri alır:

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

Örnek Yanıt

{
  "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"
    }
  ]...
}

Sonuçlar filtreleniyor

Daha ayrıntılı sonuçlar için döndürülen verileri sınırlayacak şekilde filtre uygulayabilirsiniz. Filtreleri kullanırken boyutları filtre özelliği olarak kullanmanız gerekir.

Örneğin, arka uç hizmetlerinden isteklerin HTTP fiiline göre filtrelenmiş hata sayısını almanız gerektiğini varsayalım. Amacınız, arka uç hizmeti başına kaç POST ve PUT isteğinin hata oluşturduğunu öğrenmektir. Bunu yapmak için target_url boyutunu request_verb filtresiyle birlikte kullanırsınız:

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

Örnek yanıt:

{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

Sonuçları sayfalandırma

Üretim ortamlarında, Edge Analytics API'ye yapılan bazı istekler çok büyük veri kümeleri döndürür. API, büyük veri kümelerinin kullanıcı arayüzü tabanlı bir uygulama bağlamında kolayca görüntülenmesi için yerel olarak sayfalara ayırmayı destekler.

Sonuçları sayfalandırmak için offset ve limit sorgu parametrelerini kullanın. Ayrıca, öğelerin tutarlı bir şekilde sıralanmasını sağlamak için sortby sıralama parametresini de kullanın.

Örneğin, aşağıdaki istek, son bir haftada ürün ortamındaki tüm API'lerdeki tüm hatalarla ilgili metrikleri aldığından büyük bir veri kümesi döndürme olasılığı yüksektir.

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

Kullanıcı arayüzü tabanlı uygulamanız makul bir şekilde sayfa başına 50 sonuç gösterebiliyorsa sınırı 50 olarak ayarlayabilirsiniz. 0 ilk öğe olarak sayıldığından aşağıdaki çağrı, öğeleri azalan sırada (sort=DESC varsayılandır) 0-49 olarak döndürür.

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

Sonuçların ikinci "sayfası" için aşağıdaki gibi offset sorgu parametresini kullanın. Sınır ve ofsetin aynı olduğunu unutmayın. Bunun nedeni, 0'ın ilk öğe olarak sayılmasıdır. 50 sınırı ve 0 uzaklığı ile 0-49 arasındaki öğeler döndürülür. 50'lik bir ofsetle 50-99 arasındaki öğeler döndürülür.

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