Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Edge Analytics menyediakan serangkaian dasbor interaktif, generator laporan kustom, dan kemampuan terkait. Namun, fitur ini dimaksudkan agar bersifat interaktif: Anda mengirimkan permintaan API atau UI dan permintaan tersebut akan diblokir hingga server analisis memberikan respons.
Namun, waktu penyelesaian permintaan analisis dapat habis jika terlalu lama. Jika permintaan kueri perlu memproses data dalam jumlah besar (misalnya, 100 GB), permintaan tersebut mungkin akan gagal karena waktu 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 ketika menemukan bahwa waktu kueri interaktif Anda habis. Beberapa situasi saat pemrosesan kueri asinkron mungkin menjadi alternatif yang baik meliputi:
- Menganalisis dan membuat laporan yang mencakup interval waktu yang besar.
- Menganalisis data dengan berbagai pengelompokan dimensi dan batasan lain yang menambah kompleksitas pada kueri.
- Mengelola kueri saat Anda menemukan bahwa volume data telah meningkat secara signifikan untuk beberapa pengguna atau organisasi.
Dokumen ini menjelaskan cara memulai kueri asinkron dengan menggunakan API. Anda juga dapat menggunakan UI, seperti yang dijelaskan dalam Menjalankan laporan kustom.
Membandingkan Reports API dengan UI
Membuat dan mengelola laporan kustom berisi penjelasan tentang cara menggunakan UI Edge untuk membuat dan menjalankan laporan kustom. Anda dapat menjalankan laporan tersebut secara sinkron atau asinkron.
Sebagian besar konsep untuk menghasilkan laporan kustom dengan UI berlaku untuk penggunaan API. Artinya, saat membuat laporan kustom dengan API, Anda menentukan metrics, dimensi, dan filter bawaan 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 (newline delimited), bukan 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:
Kirim kueri.
Mendapatkan status kueri.
Ambil hasil kueri.
Langkah 1. Mengirim kueri
Anda harus mengirim permintaan POST ke /queries API. 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 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 dari kueri. Dalam isi JSON, tentukan metrics, 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 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 dihasilkan 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 tanggapan:
Jika kueri masih berlangsung, 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 get results
API untuk mengambil hasil, dengan ID kueri sekali lagi adalah 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 sehingga alat yang telah didownload akan disimpan 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 bernama
response
didownload.Jika Anda menggunakan browser Chrome, download akan otomatis diterima.
Jika permintaan berhasil, dan ada kumpulan hasil bukan nol, hasilnya akan didownload ke klien sebagai file ZIP (yang dibatasi baris baru) dalam bentuk zip. Nama file yang didownload adalah:
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 sebuah 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" }
Properti | Deskripsi | Wajib diisi? |
---|---|---|
metrics
|
Array metrik. Anda dapat menentukan satu atau beberapa metrik untuk kueri yang menyertakan setiap metrik. Hanya nama metrik yang wajib diisi:
Properti "metrics":[ { "name":"response_processing_latency", "function":"avg", "alias":"average_response_time_in_seconds", "operator":"/", "value":"1000" } ] Untuk informasi selengkapnya, lihat Referensi metrik, dimensi, dan filter Analytics. |
Tidak |
dimensions
|
Array dimensi untuk mengelompokkan metrik. Untuk mengetahui informasi selengkapnya, lihat daftar dimensi yang didukung. Anda dapat menentukan beberapa dimensi. | Tidak |
timeRange
|
Rentang waktu untuk kueri.
Anda dapat menggunakan string yang telah ditetapkan berikut untuk menentukan rentang waktu:
Atau, Anda dapat menentukan "timeRange": { "start": "2018-07-29T00:13:00Z", "end": "2018-08-01T00:18:00Z" } |
Ya |
limit
|
Jumlah baris maksimum yang dapat ditampilkan dalam hasil. | Tidak |
filter
|
Ekspresi Boolean yang dapat digunakan untuk memfilter data. Ekspresi filter dapat digabungkan menggunakan istilah DAN/ATAU dan harus diberi tanda kurung sepenuhnya untuk menghindari ambiguitas. Lihat referensi metrik, dimensi, dan filter Analytics untuk mengetahui informasi selengkapnya tentang kolom yang dapat difilter. Untuk mengetahui informasi selengkapnya tentang token yang Anda gunakan untuk membuat ekspresi filter, lihat Sintaksis ekspresi filter. | Tidak |
groupByTimeUnit
|
Satuan waktu yang digunakan untuk mengelompokkan kumpulan hasil. Nilai yang valid mencakup: second , minute , hour , day , week , atau month .
Jika kueri menyertakan |
Tidak |
outputFormat
|
Format output. Nilai yang valid mencakup: csv atau json . Nilai defaultnya adalah json
yang sesuai dengan JSON yang dibatasi baris baru.
Catatan: Konfigurasikan pembatas untuk output CSV menggunakan properti |
Tidak |
csvDelimiter
|
Pemisah yang digunakan dalam file CSV, jika outputFormat ditetapkan ke csv . Default-nya adalah karakter , (koma). Karakter pembatas yang didukung termasuk koma (, ), pipa (| ), dan tab (\t ).
|
Tidak |
Sintaksis ekspresi filter
Bagian referensi ini menjelaskan token yang bisa 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)"
Token | Deskripsi | Contoh |
---|---|---|
in
|
Sertakan dalam daftar | (apiproxy in 'ethorapi','weather-api') (apiproxy in 'ethorapi') (apiproxy in 'Search','ViewItem') (response_status_code in 400,401,500,501) Catatan: String harus dalam tanda kutip. |
notin
|
Kecualikan dari daftar | (response_status_code notin 400,401,500,501) |
eq
|
Sama dengan (==)
|
(response_status_code eq 504) (apiproxy eq 'non-prod') |
ne
|
Tidak sama dengan (!=)
|
(response_status_code ne 500) (apiproxy ne 'non-prod') |
gt
|
Lebih dari (>)
|
(response_status_code gt 500) |
lt
|
Kurang dari (<)
|
(response_status_code lt 500) |
ge
|
Lebih dari atau sama dengan (>=)
|
(target_response_code ge 400) |
le
|
Kurang dari atau sama dengan (<=)
|
(target_response_code le 300) |
like
|
Menampilkan nilai true (benar) jika pola string cocok dengan pola yang disediakan.
Contoh di sebelah kanan cocok sebagai berikut: - nilai apa pun yang memiliki kata 'beli' - nilai apa pun yang diakhiri dengan 'item' - nilai apa pun yang dimulai dengan 'Prod' - nilai apa pun yang dimulai dengan 4, perhatikan response_status_code adalah numerik
|
(apiproxy like '%buy%') (apiproxy like '%item') (apiproxy like 'Prod%') |
not like
|
Menampilkan nilai salah jika pola string cocok dengan pola yang disediakan. | (apiproxy not like '%buy%') (apiproxy not like '%item') (apiproxy not like 'Prod%') |
and
|
Memungkinkan Anda menggunakan logika 'dan' untuk menyertakan lebih dari satu ekspresi filter. Filter tersebut menyertakan data yang memenuhi semua kondisi. | (target_response_code gt 399) and (response_status_code ge 400) |
or
|
Memungkinkan Anda menggunakan logika 'atau' untuk mengevaluasi berbagai kemungkinan ekspresi filter. Filter tersebut menyertakan data yang memenuhi setidaknya salah satu kondisi. | (response_size ge 1000) or (response_status_code eq 500) |
Batasan dan default
Berikut adalah daftar batasan dan default untuk fitur pemrosesan kueri asinkron.
Batasan | Default | Deskripsi |
---|---|---|
Batas panggilan kueri | Lihat deskripsi | Anda dapat melakukan hingga tujuh panggilan per jam ke API pengelolaan /queries untuk memulai laporan asinkron. Jika Anda melebihi kuota panggilan, API akan menampilkan respons HTTP 429. |
Batas kueri aktif | 10 | Anda dapat memiliki hingga 10 kueri aktif untuk satu organisasi/lingkungan. |
Nilai minimum waktu eksekusi kueri | 6 jam | Kueri yang memerlukan waktu lebih dari 6 jam akan dihentikan. |
Rentang Waktu Kueri | Lihat deskripsi | Rentang waktu maksimum yang diizinkan untuk kueri adalah 365 hari. |
Batas dimensi dan metrik | 25 | Jumlah dimensi dan metrik maksimum yang dapat Anda tentukan dalam payload kueri. |
Tentang hasil kueri
Berikut adalah contoh hasil dalam format JSON. Outputnya terdiri dari baris JSON yang dipisahkan oleh pemisah 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 jumlah pesan
Kueri untuk jumlah jumlah 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
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
Kutipan 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
Membuat 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 di 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 mencatat semua transaksi monetisasi yang berhasil dalam rentang waktu tertentu untuk serangkaian kriteria tertentu menggunakan langkah-langkah yang dijelaskan di bagian ini.
Seperti pada 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 akan dijelaskan di bawah.
Langkah 2 dan 3 sama persis dengan kueri analisis asinkron. Untuk informasi selengkapnya, lihat Cara membuat kueri analisis asinkron.
Untuk mengirimkan kueri laporan monetisasi asinkron, kirimkan 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.
Nama | Deskripsi | Default | Wajib? |
appCriteria |
ID dan organisasi untuk aplikasi tertentu yang akan disertakan dalam laporan. Jika properti ini tidak ditentukan, semua aplikasi akan disertakan dalam laporan. | T/A | Tidak |
billingMonth |
Bulan penagihan untuk laporan, seperti JULY. | T/A | Ya |
billingYear |
Tahun penagihan untuk laporan, misalnya 2015. | T/A | Ya |
currencyOption |
Mata uang untuk laporan. Nilai yang valid mencakup:
Jika Anda memilih EUR, GBP, atau USD, laporan akan menampilkan semua transaksi yang menggunakan mata uang tunggal tersebut, berdasarkan nilai tukar yang berlaku pada tanggal transaksi. |
T/A | Tidak |
devCriteria
|
ID developer atau alamat email, dan nama organisasi untuk developer tertentu yang akan disertakan dalam laporan. Jika properti ini tidak ditentukan, semua developer akan disertakan dalam laporan. Contoh: "devCriteria":[{ "id":"RtHAeZ6LtkSbEH56", "orgId":"my_org"} ] |
T/A | Tidak |
fromDate
|
Tanggal mulai laporan dalam UTC. | T/A | Ya |
monetizationPakageIds |
ID dari satu atau beberapa paket API yang akan disertakan dalam laporan. Jika properti ini tidak ditentukan, semua paket API akan disertakan dalam laporan. | T/A | Tidak |
productIds
|
ID dari satu atau beberapa produk API untuk disertakan dalam laporan. Jika properti ini tidak ditentukan, semua produk API akan disertakan dalam laporan. | T/A | Tidak |
ratePlanLevels |
Jenis paket tarif yang akan disertakan dalam laporan. Nilai yang valid meliputi:
Jika properti ini tidak ditentukan, paket tarif khusus developer dan standar akan disertakan dalam laporan. |
T/A | Tidak |
toDate
|
Tanggal akhir laporan dalam UTC. | T/A | Ya |
Misalnya, permintaan berikut menghasilkan laporan monetisasi asinkron untuk bulan Juni 2017 untuk produk API dan ID developer yang ditentukan. Tanggal dan waktu laporan fromDate
dan toDate
menggunakan UTC/GMT serta dapat mencakup 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