Menggunakan API laporan kustom asinkron

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Edge Analytics menyediakan serangkaian dasbor interaktif yang beragam, generator laporan kustom, dan kemampuan terkait. Namun, fitur ini dimaksudkan untuk bersifat interaktif: Anda mengirimkan permintaan API atau UI, dan permintaan tersebut diblokir hingga server analisis memberikan respons.

Namun, permintaan analisis dapat habis waktunya jika memerlukan waktu terlalu lama untuk diselesaikan. Jika permintaan kueri perlu memproses data dalam jumlah besar (misalnya, 100 GB), permintaan tersebut mungkin gagal karena waktu tunggu habis.

Pemrosesan kueri asinkron memungkinkan Anda membuat kueri untuk set data yang sangat besar dan mengambil hasilnya di lain waktu. Anda dapat mempertimbangkan untuk menggunakan kueri offline saat menemukan bahwa kueri interaktif Anda habis waktu tunggunya. Beberapa situasi saat pemrosesan kueri asinkron mungkin merupakan alternatif yang baik meliputi:

• Menganalisis dan membuat laporan yang mencakup interval waktu yang besar.
• Menganalisis data dengan berbagai dimensi pengelompokan dan batasan lainnya yang menambah kompleksitas kueri.
• Mengelola kueri saat Anda mendapati bahwa volume data telah meningkat secara signifikan untuk beberapa pengguna atau organisasi.

Dokumen ini menjelaskan cara memulai kueri asinkron menggunakan API. Anda juga dapat menggunakan UI, seperti yang dijelaskan dalam Menjalankan laporan kustom.

Membandingkan API laporan dengan UI

Membuat dan mengelola laporan kustom menjelaskan cara menggunakan UI Edge untuk membuat dan menjalankan laporan kustom. Anda dapat menjalankan laporan tersebut secara sinkron atau asinkron.

Sebagian besar konsep untuk membuat laporan kustom dengan UI berlaku untuk penggunaan API. Artinya, saat membuat laporan kustom dengan API, Anda menentukan metrik, dimensi, dan filter yang disertakan dalam Edge, serta metrik kustom apa pun yang Anda buat menggunakan kebijakan StatisticsCollector.

Perbedaan utama antara laporan yang dihasilkan di UI dan di API adalah laporan yang dihasilkan dengan API ditulis ke file CSV atau JSON (dipisahkan baris baru), bukan ke laporan visual yang ditampilkan di UI.

Batasan di Apigee Hybrid

Apigee hybrid menerapkan batas ukuran 30 MB pada set data hasil.

Cara membuat kueri analisis asinkron

Anda membuat kueri analisis asinkron dalam tiga langkah:

1. Kirim kueri.

2. Dapatkan status kueri.

3. Ambil hasil kueri.

Langkah 1. Mengirim kueri

Anda harus mengirim permintaan POST ke API /queries. API ini memberi tahu Edge untuk memproses permintaan Anda di latar belakang. Jika pengiriman kueri berhasil, API akan menampilkan status 201 dan ID yang akan Anda gunakan untuk merujuk ke kueri di langkah-langkah berikutnya.

Contoh:

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

Isi permintaan adalah deskripsi JSON kueri. Dalam isi JSON, tentukan metrik, dimensi, dan filter yang menentukan laporan.

Berikut adalah contoh file json-query-file:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

Lihat Tentang isi permintaan di bawah untuk mengetahui deskripsi lengkap sintaksis isi permintaan.

Contoh respons:

Perhatikan bahwa ID kueri 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd disertakan dalam respons. Selain status HTTP 201, state dari enqueued berarti permintaan berhasil.

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",
}

Langkah 2. Mendapatkan status kueri

Lakukan panggilan GET untuk meminta status kueri. Anda memberikan ID kueri yang ditampilkan dari panggilan POST. Contoh:

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

Contoh respons:

Jika kueri masih dalam proses, Anda akan mendapatkan respons seperti ini, dengan state adalah 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"
}

Setelah kueri berhasil diselesaikan, Anda akan melihat respons seperti ini, dengan state ditetapkan ke 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"
}

Langkah 3. Mengambil hasil kueri

Setelah status kueri menjadi completed, Anda dapat menggunakan API get results untuk mengambil hasilnya, dengan ID kueri kembali menjadi 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

Untuk mengambil file yang didownload, Anda perlu mengonfigurasi alat yang digunakan agar alat tersebut menyimpan file yang didownload ke sistem Anda. Contoh:

• Jika menggunakan cURL, Anda dapat menggunakan opsi -O -J, seperti yang ditunjukkan di atas.

• Jika menggunakan Postman, Anda harus memilih tombol Save and Download. Dalam hal ini, file zip yang disebut response akan didownload.

• Jika Anda menggunakan browser Chrome, download akan otomatis diterima.

Jika permintaan berhasil, dan ada kumpulan hasil yang bukan nol, hasilnya akan didownload ke klien sebagai file JSON yang dikompresi (dibatasi baris baru). Nama file yang didownload akan menjadi:

OfflineQueryResult-<query-id>.zip

Contoh:

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

File ZIP berisi file arsip .gz dari hasil JSON. Untuk mengakses file JSON, ekstrak file download, lalu gunakan perintah gzip untuk mengekstrak file JSON:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

Tentang isi permintaan

Bagian ini menjelaskan setiap parameter yang dapat Anda gunakan dalam isi permintaan JSON untuk kueri. Untuk mengetahui detail tentang metrik dan dimensi yang dapat Anda gunakan dalam kueri, lihat Referensi 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"
}

Sintaksis ekspresi filter

Bagian referensi ini menjelaskan token yang dapat Anda gunakan untuk membuat ekspresi filter dalam isi permintaan. Misalnya, ekspresi berikut menggunakan token "ge" (lebih besar dari atau sama dengan):

"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)

Batasan dan default

Berikut adalah daftar batasan dan default untuk fitur pemrosesan kueri asinkron.

Tentang hasil kueri

Berikut adalah contoh hasil dalam format JSON. Output terdiri dari baris JSON yang dipisahkan oleh pembatas baris baru:

{"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"}    
…

Anda dapat mengambil hasil dari URL hingga masa berlaku data di repositori berakhir. Lihat Batasan dan default.

Contoh

Contoh 1: Jumlah pesan

Buat kueri untuk jumlah total pesan selama 60 menit terakhir.

Kueri

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

Isi Permintaan dari last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Contoh 2: Rentang waktu kustom

Buat kueri menggunakan rentang waktu kustom.

Kueri

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

Isi permintaan dari 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"
   }
}

Contoh 3: Transaksi per menit

Buat kueri pada metrik untuk transaksi per menit (tpm).

Kueri

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

Isi permintaan dari tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Contoh hasil

Cuplikan dari file hasil:

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

Contoh 4: Menggunakan ekspresi filter

Buat kueri dengan ekspresi filter yang menggunakan operator boolean.

Kueri

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

Isi permintaan dari 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"
   }
}

Contoh 5: Meneruskan ekspresi dalam parameter metrik

Kueri dengan ekspresi yang diteruskan sebagai bagian dari parameter metrik. Anda hanya dapat menggunakan ekspresi satu operator sederhana.

Kueri

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

Isi permintaan dari metricsExpression.json

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

Cara membuat kueri laporan monetisasi asinkron

Anda dapat merekam semua transaksi monetisasi yang berhasil dalam rentang waktu tertentu untuk kumpulan kriteria tertentu menggunakan langkah-langkah yang dijelaskan di bagian ini.

Seperti kueri analisis asinkron, Anda membuat kueri laporan monetisasi asinkron dalam tiga langkah: (1) mengirimkan kueri, (2) mendapatkan status kueri, dan (3) mengambil hasil kueri.

Langkah 1, mengirimkan kueri, dijelaskan di bawah.

Langkah 2 dan 3 sama persis dengan kueri analisis asinkron. Untuk mengetahui informasi selengkapnya, lihat Cara membuat kueri analisis asinkron.

Untuk mengirimkan kueri untuk laporan monetisasi asinkron, buat permintaan POST ke /mint/organizations/org_id/async-reports.

Secara opsional, Anda dapat menentukan lingkungan dengan meneruskan parameter kueri environment. Jika tidak ditentukan, parameter kueri akan ditetapkan secara default ke prod. Contoh:

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

Dalam isi permintaan, tentukan kriteria penelusuran berikut.

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

Misalnya, permintaan berikut menghasilkan laporan monetisasi asinkron untuk bulan Juni 2017 untuk produk API dan ID developer yang ditentukan. Tanggal dan waktu fromDate dan toDate laporan menggunakan zona waktu UTC/GMT dan dapat menyertakan waktu.

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