Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Ringkasan
Kebijakan DataCapture mengambil data (seperti payload, header HTTP, dan parameter jalur atau kueri) dari proxy API untuk digunakan di Analytics. Anda dapat menggunakan data yang diambil dalam laporan Analytics kustom, serta untuk menerapkan aturan yang logis, monetisasi, dan pemantauan.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Resource kolektor data
Untuk menggunakan kebijakan DataCapture
, Anda harus membuat resource
pengumpul data terlebih dahulu. Untuk langkah-langkah membuat resource pengumpul data menggunakan UI Apigee dan Apigee API, lihat Membuat pengumpul data.
<DataCapture>
Elemen <DataCapture>
menentukan kebijakan DataCapture
.
<DataCapture async="true" continueOnError="true" enabled="true" name="DC">
Berikut adalah contoh kebijakan DataCapture
:
<DataCapture name="DC-1"> <Capture> <DataCollector>dc_data_collector</DataCollector> <Collect ref="my_data_variable" /> </Capture> </DataCapture>
Elemen utama kebijakan DataCapture
adalah elemen <Capture>
, yang menentukan cara mengambil data. Kode ini memiliki dua elemen turunan yang diperlukan:
- Elemen
<DataCollector>
, yang menentukan resource REST pengumpul data. Dalam hal ini, resource diberi namadc_data_collector
. - Elemen
<Collect>
, yang menentukan cara untuk mengambil data.
Dalam contoh sederhana ini, data diekstrak dari variabel bernama my_data_variable
, yang telah dibuat di tempat lain di proxy.
Variabel ditentukan oleh atribut ref
.
Elemen <Collect>
juga menyediakan beberapa cara lain untuk mengambil data dari berbagai sumber melalui elemen turunannya.
Lihat Contoh untuk mengetahui contoh lain pengambilan data dengan kebijakan DataCapture
.
Elemen DataCapture
memiliki sintaksis berikut.
<DataCapture name="capturepayment" continueOnError="false" enabled="true"> <DisplayName>Data-Capture-Policy-1</DisplayName> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit> <!-- Existing Variable --> <Capture> <Collect ref="existing-variable" default="0"></Collect> <DataCollector>dc_1</DataCollector> </Capture> <!-- JSONPayload --> <Capture> <DataCollector>dc_2</DataCollector> <Collect default="0"> <Source>request</Source> <JSONPayload> <JSONPath>result.var</JSONPath> </JSONPayload> </Collect> </Capture> <!-- URIPath --> <Capture> <DataCollector>dc_3</DataCollector> <Collect default="0"> <URIPath> <!-- All patterns must specify a single variable to extract named $ --> <Pattern ignoreCase="false">/foo/{$}</Pattern> <Pattern ignoreCase="false">/foo/bar/{$}</Pattern> </URIPath> </Collect> </Capture> </DataCapture>
Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
continueOnError |
false | Opsional | Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
|
enabled |
true | Opsional | Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur. |
async |
false | Tidak digunakan lagi | Atribut ini sudah tidak digunakan lagi. |
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <DataCapture>
.
Elemen Turunan | Diperlukan | Deskripsi |
---|---|---|
<Capture> |
Diperlukan | Merekam data untuk variabel tertentu. |
Contoh
Contoh berikut mengilustrasikan berbagai cara untuk menggunakan kebijakan
DataCapture
.
Merekam data untuk variabel built-in
Contoh kode di bawah mengilustrasikan cara mengambil data untuk variabel bawaan, message.content
, yang berisi konten permintaan, respons, atau pesan error. Lihat
Variabel alur untuk
informasi selengkapnya tentang variabel bawaan.
<DataCapture name="DC-FullMessage"> <Capture> <DataCollector>dc_data_collector</DataCollector> <Collect ref="message.content" /> </Capture> </DataCapture>
Dalam kode di atas, atribut ref
dari elemen </Collect>
menentukan variabel yang akan diambil, yang dalam contoh ini
bernama "message.content"
.
Contoh ini mengambil data dengan elemen <Capture>
, yang juga berisi elemen <DataCollector>
yang menentukan nama resource kolektor data.
Mengambil data inline
Contoh berikutnya menunjukkan cara mengambil data secara inline menggunakan <JSONPayload>
, elemen turunan dari elemen <Collect>
.
<DataCapture name="DC-Currency"> <Capture> <DataCollector>dc_data_collector<DataCollector> <Collect> <JSONPayload> <JSONPath>$.results[0].currency</JSONPath> </JSONPayload> </Collect> </Capture> </DataCapture>
Dalam kode di atas:
- Elemen
<JSONPayload>
menentukan pesan berformat JSON tempat nilai variabel diekstrak. - Elemen
<JSONPath>
menentukan jalur JSON yang digunakan untuk mengekstrak nilai dari pesan, yang dalam hal ini adalah$.results[0].currency
.
Sebagai ilustrasi, anggaplah nilai yang diekstrak pada saat pesan diterima adalah 1120
. Kemudian, hasil entri yang dikirim ke Analytics akan
{ "dc_data_collector": "1120" }
<Ambil>
Elemen <Capture>
menentukan cara mengambil data.
<Capture />
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <Capture>
.
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<DataCollector> |
Wajib | Menentukan resource kolektor data. |
<Collect> |
Wajib | Menentukan cara untuk mengambil data. |
<DataCollector>
Elemen <DataCollector>
menentukan
resource pengumpul data.
<DataCollector>dc_data_collector</DataCollector>Tabel berikut menjelaskan atribut elemen
<DataCollector>
.
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
cakupan |
Tentukan atribut ini dan tetapkan nilainya ke |
T/A | Opsional | String |
Isi elemen <DataCollector>
berisi nama
resource pengumpul data.
<Kumpulkan>
Elemen <Collect>
menentukan cara untuk mengambil data.
<Collect ref="existing-variable" default="0"/>
Tabel berikut menjelaskan atribut elemen <Collect>
.
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
referensi |
Variabel yang Anda gunakan untuk mengambil data. |
T/A | Opsional—Jika ref dihilangkan, hanya salah satu dari hal berikut yang harus ditentukan: QueryParam , Header , FormParam , URIPath , JSONPayload , atau XMLPayload .
|
String |
default | Menentukan nilai yang dikirim ke Analytics jika nilai variabel tidak diisi saat runtime. Misalnya, jika Anda menetapkan
default="0" , nilai yang dikirim ke Analytics adalah 0.
|
Jika Anda tidak menentukan nilai
default , dan nilai variabel
tidak diisi saat runtime, nilai yang dikirim ke Analytics adalah null
untuk variabel numerik atau "Not set" untuk variabel string.
|
Diperlukan | String |
Data dapat diambil dari variabel yang ada menggunakan atribut ref
, atau
oleh elemen turunan <Collect>
.
Elemen turunan dari <Collect>
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <Collect>
:
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<Source> |
Opsional | Menentukan variabel yang akan diuraikan. |
<URIPath> |
Opsional | Mengekstrak nilai dari proxy.pathsuffix
pesan sumber permintaan. |
<QueryParam> |
Opsional | Mengekstrak nilai dari parameter kueri yang ditentukan untuk pesan sumber permintaan. |
<Header> |
Opsional | Mengekstrak nilai dari header HTTP yang ditentukan dari pesan respons atau permintaan yang ditentukan. |
<FormParam> |
Opsional | Mengekstrak nilai dari parameter formulir yang ditentukan untuk pesan respons atau permintaan yang ditentukan. |
<JSONPayload> |
Opsional | Menentukan pesan berformat JSON yang menjadi asal ekstraksi nilai variabel. |
<XMLPayload> |
Opsional | Menentukan pesan berformat XML yang akan digunakan untuk mengekstrak nilai variabel. |
<Sumber>
Menentukan variabel yang akan diuraikan. Nilai
<Source>
ditetapkan secara default ke message
. Nilai message
bersifat sensitif konteks. Dalam alur permintaan, message
me-resolve pesan permintaan. Dalam
alur respons, message
me-resolve ke pesan respons.
Meskipun kebijakan ini sering digunakan untuk mengekstrak informasi dari pesan permintaan atau respons, Anda dapat menggunakannya untuk mengekstrak informasi dari variabel apa pun. Misalnya, Anda dapat menggunakannya untuk mengekstrak
informasi dari entity yang dibuat oleh kebijakan AccessEntity, dari data
yang ditampilkan oleh kebijakan ServiceCallout, atau mengekstrak informasi dari objek XML atau JSON.
Jika <Source>
tidak dapat diselesaikan, atau di-resolve menjadi jenis non-pesan,
kebijakan akan gagal merespons.
Nilai Default | T/A |
Wajib? | Opsional |
Type | String |
Elemen Induk |
<Collect> |
Elemen Turunan | T/A |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
clearPayload |
Tetapkan ke true jika Anda ingin menghapus payload yang ditentukan dalam Gunakan opsi |
false |
Opsional | Boolean |
<Source clearPayload="true|false">request</Source>
<URIPath>
Mengekstrak nilai dari proxy.pathsuffix
pesan sumber request
. Jalur yang diterapkan ke pola adalah proxy.pathsuffix
, yang tidak menyertakan jalur dasar untuk proxy API. Jika pesan sumber me-resolve ke jenis pesan response
, elemen ini tidak akan melakukan apa pun.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan | <Pola> |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
ignoreCase | Menyatakan untuk mengabaikan huruf besar/kecil saat mencocokkan pola. |
false |
Opsional | Boolean |
<Collect> <URIPath> <Pattern ignoreCase="false">/foo/{$}</Pattern> </URIPath> </Collect>
Anda dapat menggunakan beberapa elemen <Pattern>
:
<URIPath> <Pattern ignoreCase="false">/foo/{$}</Pattern> <Pattern ignoreCase="false">/foo/bar/{$}</Pattern> </URIPath>
<QueryParam>
Mengekstrak nilai dari parameter kueri yang ditentukan untuk pesan sumber request
. Jika pesan sumber me-resolve ke jenis pesan response
, elemen ini tidak melakukan apa pun.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan | <Pola> |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
name | Menentukan nama parameter kueri. Jika beberapa parameter kueri memiliki nama yang sama, gunakan referensi yang diindeks, dengan instance pertama parameter kueri tidak memiliki indeks, yang kedua ada di indeks 2, yang ketiga ada di indeks 3, dst. |
T/A |
Diperlukan | String |
<Collect> <QueryParam name="code"> <Pattern ignoreCase="true">{$}</Pattern> </QueryParam> </Collect>
Jika beberapa parameter kueri memiliki nama yang sama, gunakan indeks untuk mereferensikan parameter:
<Collect> <QueryParam name="code.2"> <Pattern ignoreCase="true">{$}</Pattern> </QueryParam> </Collect>
Catatan: Anda harus menentukan satu variabel bernama {$}
.
Mungkin ada beberapa elemen Pattern
yang unik, tetapi pola pertama yang cocok akan
diselesaikan untuk permintaan tertentu.
<Header>
Mengekstrak nilai dari header HTTP yang ditentukan untuk pesan request
atau response
yang ditentukan. Jika beberapa header memiliki
nama yang sama, nilainya akan disimpan dalam array.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan | <Pola> |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
name | Menentukan nama header tempat Anda mengekstrak nilai. Jika beberapa
header memiliki nama yang sama, gunakan referensi yang diindeks, dengan instance pertama
header tidak memiliki indeks, yang kedua ada di indeks 2, yang ketiga ada di indeks 3, dst. Gunakan
.values untuk mendapatkan semua header dalam array. |
T/A |
Diperlukan | String |
<Collect> <Header name="my_header"> <Pattern ignoreCase="false">Bearer {$}</Pattern> </Header> </Collect>
Jika beberapa header memiliki nama yang sama, gunakan indeks untuk mereferensikan header individual dalam array:
<Collect> <Header name="my_header.2"> <Pattern ignoreCase="true">{$}</Pattern> </Header> </Collect>
Atau perintah berikut untuk menampilkan semua header dalam array:
<Collect> <Header name="my_header.values"> <Pattern ignoreCase="true">{$}</Pattern> </Header> </Collect>
<FormParam>
Mengekstrak nilai dari parameter formulir yang ditentukan untuk pesan request
atau response
yang ditentukan. Parameter formulir hanya dapat diekstrak jika header Content-Type
dari pesan yang ditentukan adalah application/x-www-form-urlencoded
.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan | <Pola> |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
name | Nama parameter formulir tempat Anda mengekstrak nilai. |
T/A |
Opsional | String |
<Collect> <FormParam name="greeting"> <Pattern>hello {$}</Pattern> </FormParam> </Collect>
<JSONPayload>
Menentukan pesan berformat JSON yang menjadi asal ekstraksi nilai variabel. Ekstraksi JSON hanya dilakukan jika header Content-Type
pesan adalah application/json
.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan | <JSONPath> |
<Collect> <JSONPayload> <JSONPath>$.results[0].currency</JSONPath> </JSONPayload> </Collect>
<JSONPath>
Elemen turunan wajib dari elemen <JSONPayload>
. Menentukan jalur JSON yang digunakan untuk mengekstrak nilai dari pesan berformat JSON.
Nilai Default | T/A |
Wajib? | Diperlukan |
Type | String |
Elemen Induk |
<JSONPayload> |
Elemen Turunan | T/A |
<JSONPath>$.rss.channel.title</JSONPath>
<XMLPayload>
Menentukan pesan berformat XML yang akan digunakan untuk mengekstrak nilai variabel. Payload XML
hanya diekstrak jika header Content-Type
pesan adalah text/xml
, application/xml
,
atau application/*+xml
.
Nilai Default | T/A |
Wajib? | Opsional |
Type | Kompleks |
Elemen Induk |
<Collect> |
Elemen Turunan |
<Namespaces> <XPath> |
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <XMLPayload>
.
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<Namespaces> |
Opsional | Menentukan nol atau beberapa namespace yang akan digunakan dalam evaluasi XPath. |
<XPath> |
Diperlukan | Menentukan XPath yang ditentukan untuk variabel. |
<Collect> <XMLPayload> <Namespaces> <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace> <Namespace prefix="ns1">http://ns1.example.com/operations</Namespace> </Namespaces> <!-- get the local name of the SOAP operation --> <XPath>local-name(/soap:Envelope/soap:Body/ns1:*[1])</XPath> </XMLPayload> </Collect>
<Namespaces>
Menentukan kumpulan namespace yang dapat digunakan dalam ekspresi XPath. Sebagai contoh.
<Collect> <XMLPayload> <Namespaces> <Namespace prefix="maps">http://maps.example.com</Namespace> <Namespace prefix="places">http://places.example.com</Namespace> </Namespaces> <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint/places:name</XPath> </XMLPayload> </Collect>
Jika tidak menggunakan namespace dalam ekspresi XPath, Anda dapat menghilangkan atau menjadikan elemen
<Namespaces>
sebagai komentar, seperti yang ditunjukkan contoh berikut:
<Collect> <XMLPayload> <!-- <Namespaces/> --> <XPath>/Directions/route/leg/name</XPath> </XMLPayload> </Collect>
<Namespace>
Menentukan satu namespace dan awalan yang sesuai untuk digunakan dalam ekspresi XPath. Sebagai contoh.
Nilai Default | T/A |
Wajib? | Opsional |
Type | String |
Elemen Induk |
<Namespaces> |
Elemen Turunan | T/A |
Atribut
Atribut | Deskripsi | Default | Wajib? | Jenis |
---|---|---|---|---|
prefix |
Awalan yang Anda gunakan untuk merujuk ke namespace dalam ekspresi xpath. Awalan ini tidak harus sama dengan yang digunakan dalam dokumen XML asli. |
T/A |
Diperlukan | String |
<Collect> <XMLPayload> <Namespaces> <Namespace prefix="maps">http://maps.example.com</Namespace> </Namespaces> <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint</XPath> </XMLPayload> </Collect>
<XPath>
Elemen turunan yang diperlukan dari elemen XMLPayload. Menentukan XPath yang ditentukan untuk variabel tersebut. Hanya ekspresi XPath 1.0 yang didukung.
Nilai Default | T/A |
Wajib? | Diperlukan |
Type | String |
Elemen Induk |
<XMLPayload> |
Elemen Turunan | T/A |
<XPath>/test/example</XPath>
Catatan: Jika menggunakan namespace dalam ekspresi XPath, Anda harus mendeklarasikan
namespace di
bagian <XMLPayload><Namespaces>
kebijakan.
<ThrowExceptionOnLimit>
Elemen <ThrowExceptionOnLimit>
menentukan apa yang terjadi saat batas pengambilan jumlah variabel atau ukuran maksimum sebuah variabel tercapai. Lihat Menerapkan batas pengambilan gambar.
Nilai <ThrowExceptionOnLimit>
dapat berupa salah satu dari yang berikut:
false
: Data untuk variabel dikirim ke Analytics.true
: Pesan error ditampilkan, dan data tidak dikirim ke Analytics.
Referensi Error
Error runtime
Tabel di bawah ini menjelaskan error runtime, yang dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Penyebab |
---|---|
DataCollectorTypeMismatch |
Nilai yang akan diambil tidak cocok dengan jenis |
ExtractionFailure |
Ekstraksi data gagal. |
UnresolvedVariable |
Variabel tidak ada. |
VariableCountLimitExceeded |
Jumlah variabel yang ditangkap melampaui batas jumlah variabel 100 variabel |
VariableValueLimitExceeded |
Ukuran nilai yang diambil melampaui batas variabel tunggal, yaitu 400 byte. |
MsgContentParsingFailed |
Konten pesan gagal diuraikan menjadi XML atau JSON. |
InvalidMsgContentType |
Jenis konten pesan tidak cocok dengan jenis konten pesan yang diharapkan dalam klausa tangkapan kebijakan. |
NonMsgVariable |
Nilai elemen <Source> tidak mereferensikan variabel pesan. |
JSONPathQueryFailed |
Kueri JSONPath gagal di-resolve ke sebuah nilai. |
PrivateVariableAccess |
Upaya untuk mengakses variabel pribadi gagal. |
XPathEvaluationFailed |
XPath gagal di-resolve ke sebuah nilai. |
Error runtime ditampilkan dengan dua cara:
- Respons error kembali ke klien (
continueOnError=false
)Jika atribut
continueOnError
kebijakan disetel kefalse
, error yang terjadi selama eksekusi kebijakan akan membatalkan pemrosesan pesan dan menampilkan pesan error deskriptif. Kebijakan ini akan mencoba mencatat semua error yang relevan dalam kebijakan pengambilan data sebelum menampilkan pesan. DataCapture
kolom analisis errorKolom
dataCapturePolicyErrors
berisi daftar semua error yang terjadi. Contoh tampilannya dalam peta data analisis ditampilkan di bawah ini:# Example payload [ { errorType: TypeMismatch, policyName: MyDataCapturePolicy-1, dataCollector: purchaseValue }, { errorType: MaxValueSizeLimitReached, policyName: MyDataCapturePolicy-1, dataCollector: purchasedItems }, ]
Kolom ini tunduk pada batas ukuran variabel 400 byte.
Error saat deployment
Kode kesalahan | Penyebab |
---|---|
DeploymentAssertionError |
DataCollector yang dirujuk dalam kebijakan tidak dapat ditemukan di organisasi selama deployment. |
JsonPathCompilationFailed |
Gagal mengompilasi dengan JSONPath yang ditentukan. |
XPathCompilationFailed |
Jika awalan atau nilai yang digunakan dalam elemen XPath bukan bagian dari namespace yang dideklarasikan dalam kebijakan, deployment proxy API akan gagal. |
PatternCompilationFailed |
Kompilasi pola gagal. |
Menemukan Error DataCapture
di alat Debug
Variabel dataCapturePolicyErrors
tersedia di alat Debug.
Ini adalah alat tambahan yang dapat Anda gunakan untuk menemukan error tanpa membuka Analytics.
Misalnya, Anda dapat melihat error yang terjadi jika mengupgrade versi runtime hybrid dan secara tidak sengaja merusak analisis dalam proxy yang sudah di-deploy.
Menerapkan batas pengambilan
Apigee menerapkan batasan berikut pada variabel dalam data yang diambil:
- Jumlah variabel yang diizinkan adalah 100.
- Ukuran maksimum setiap variabel (termasuk nilai daftar) adalah 400 byte.
Saat menjalankan Kebijakan Pengambilan Data, sebelum nilai ditambahkan ke peta pengambilan data dalam konteks pesan:
- Jika batas jumlah variabel telah tercapai, variabel baru akan dihapus.
- Jika batas ukuran variabel telah tercapai, nilai akan dipangkas agar sesuai dengan batas yang diinginkan.
Pada kedua kasus tersebut:
- Pesan debug akan dicatat ke log Pemroses Pesan.
- Pesan error
limit reached
akan ditambahkan kedataCapturePolicyErrors
, yang akan tersedia di Analytics dan Debug. Catatan: Hanya satu pesan error guna mencapai jumlah maksimum variabel yang diizinkan yang akan ditambahkan. - Jika <ThrowExceptionOnLimit> adalah
true
, data tidak akan dikirim ke Analytics dan akan menampilkan error ke klien.