Kebijakan DataCapture

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat 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 monetisasi, dan aturan pemantauan.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Resource pengumpul data

Untuk menggunakan kebijakan DataCapture, Anda harus membuat resource pengumpul data terlebih dahulu. Untuk mengetahui 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 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 pengambilan data. Elemen ini memiliki dua elemen turunan wajib:

• Elemen <DataCollector>, yang menentukan resource REST pengumpul data. Dalam hal ini, resource diberi nama dc_data_collector.
• Elemen <Collect>, yang menentukan cara pengambilan data.

Dalam contoh sederhana ini, data diekstrak dari variabel bernama my_data_variable, yang telah dibuat di tempat lain dalam 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 lainnya tentang 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 umum untuk semua kebijakan:

Tabel berikut memberikan deskripsi umum elemen turunan <DataCapture>.

Contoh

Contoh berikut mengilustrasikan berbagai cara untuk menggunakan kebijakan DataCapture.

Merekam data untuk variabel bawaan

Contoh kode di bawah ini menggambarkan 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 pengumpul data.

Mengambil data secara inline

Contoh berikutnya menunjukkan cara merekam 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 yang digunakan untuk mengekstrak nilai variabel.
• Elemen <JSONPath> menentukan jalur JSON yang digunakan untuk mengekstrak nilai dari pesan, yang dalam hal ini adalah $.results[0].currency.

Sebagai ilustrasi, misalkan nilai yang diekstrak pada saat pesan diterima adalah 1120. Kemudian, entri yang dihasilkan dan dikirim ke Analytics adalah

{
    "dc_data_collector": "1120"
}

<Capture>

Elemen <Capture> menentukan cara pengambilan data.

<Capture />

Tabel berikut memberikan deskripsi umum elemen turunan <Capture>.

<DataCollector>

Elemen <DataCollector> menentukan resource pengumpul data.

<DataCollector>dc_data_collector</DataCollector>

Isi elemen <DataCollector> berisi nama resource pengumpul data.

<Collect>

Elemen <Collect> menentukan cara pengambilan data.

<Collect ref="existing-variable" default="0"/>

Tabel berikut menjelaskan atribut elemen <Collect>.

Data dapat diambil dari variabel yang ada menggunakan atribut ref, atau oleh elemen turunan <Collect>.

Elemen turunan <Collect>

Tabel berikut memberikan deskripsi umum tentang elemen turunan dari <Collect>:

<Source>

Menentukan variabel yang memberi nama pesan yang akan diuraikan. Nilai <Source> secara default adalah message. Nilai message peka konteks. Dalam alur permintaan, message diselesaikan ke pesan permintaan. Dalam alur respons, message diselesaikan ke pesan respons.

Jika variabel yang ditentukan dalam <Source> tidak dapat diselesaikan, atau diselesaikan ke jenis non-pesan, kebijakan tidak akan merespons.

<Source >request</Source>

<URIPath>

Mengekstrak nilai dari proxy.pathsuffix pesan sumber request. Jalur yang diterapkan ke pola adalah proxy.pathsuffix, yang tidak menyertakan basepath untuk proxy API. Jika pesan sumber di-resolve ke jenis pesan response, elemen tidak melakukan apa pun.

Atribut

<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 dari pesan sumber request. Jika pesan sumber diselesaikan ke jenis pesan response, elemen tidak melakukan apa pun.

Atribut

<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

Jika beberapa parameter kueri memiliki nama yang sama, gunakan indeks untuk merujuk parameter:

<Collect>
    <QueryParam name="code.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

Catatan: Anda harus menentukan satu variabel bernama {$}. Mungkin ada beberapa elemen Pattern unik, tetapi pola yang cocok pertama akan diselesaikan untuk permintaan tertentu.

<Header>

Mengekstrak nilai dari header HTTP yang ditentukan dari pesan request atau response yang ditentukan. Jika beberapa header memiliki nama yang sama, nilainya disimpan dalam array.

Atribut

<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

Jika beberapa header memiliki nama yang sama, gunakan indeks untuk merujuk ke setiap header dalam array:

<Collect>
    <Header name="my_header.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

Atau yang berikut untuk mencantumkan semua header dalam array:

<Collect>
    <Header name="my_header.values">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

<FormParam>

Mengekstrak nilai dari parameter formulir tertentu dari pesan request atau response tertentu. Parameter formulir hanya dapat diekstrak jika header Content-Type dari pesan yang ditentukan adalah application/x-www-form-urlencoded.

Atribut

<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

Menentukan pesan berformat JSON yang akan digunakan untuk mengekstrak nilai variabel. Ekstraksi JSON hanya dilakukan jika header Content-Type pesan adalah application/json.

<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

Elemen turunan yang diperlukan dari elemen <JSONPayload>. Menentukan jalur JSON yang digunakan untuk mengekstrak nilai dari pesan berformat JSON.

<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.

Tabel berikut memberikan deskripsi umum elemen turunan <XMLPayload>.

<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. 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 Anda tidak menggunakan namespace dalam ekspresi XPath, Anda dapat menghapus atau mengomentari elemen <Namespaces>, 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. Contoh.

Atribut

<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 wajib dari elemen XMLPayload. Menentukan XPath yang ditentukan untuk variabel. Hanya ekspresi XPath 1.0 yang didukung.

   <XPath>/test/example</XPath>

Catatan: Jika Anda menggunakan namespace dalam ekspresi XPath, Anda harus mendeklarasikan namespace dalam bagian <XMLPayload><Namespaces> kebijakan.

<ThrowExceptionOnLimit>

Elemen <ThrowExceptionOnLimit> menentukan apa yang terjadi saat batas pengambilan pada jumlah variabel atau ukuran maksimum variabel tercapai. Lihat Menerapkan batas pengambilan.

Nilai <ThrowExceptionOnLimit> dapat berupa salah satu dari berikut:

• false: Data untuk variabel dikirim ke Analytics.
• true: Pesan error akan ditampilkan, dan data tidak dikirim ke Analytics.

Referensi Error

Error runtime

Tabel di bawah menjelaskan error runtime, yang dapat terjadi saat kebijakan dijalankan.

Error runtime ditampilkan dengan dua cara:

• Respons error kembali ke klien (continueOnError=false)

  Jika atribut continueOnError kebijakan disetel ke false, error yang terjadi selama eksekusi kebijakan akan menghentikan pemrosesan pesan dan menampilkan pesan error deskriptif. Kebijakan ini akan mencoba menangkap semua error yang relevan dalam kebijakan pengambilan data sebelum menampilkan pesan.

• Kolom analisis error DataCapture

  Kolom dataCapturePolicyErrors berisi daftar semua error yang telah terjadi. Contoh tampilannya di peta data analisis ditunjukkan di bawah:

  # 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

Menemukan DataCapture Error 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 menangkap error yang terjadi jika Anda mengupgrade versi runtime hybrid dan secara tidak sengaja merusak analisis dalam proxy yang sudah di-deploy.

Menerapkan batas pengambilan

Apigee menerapkan batas berikut pada variabel dalam data yang diambil:

• Jumlah variabel yang diizinkan adalah 100.
• Ukuran maksimum setiap variabel (termasuk nilai daftar) adalah 400 byte.

Saat eksekusi 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 dalam batas yang diinginkan.

Dalam kedua kasus:

• Pesan debug akan dicatat ke log Message Processor.
• Pesan error limit reached akan ditambahkan ke dataCapturePolicyErrors, yang akan tersedia di Analytics dan Debug. Catatan: Hanya satu pesan error untuk mencapai jumlah maksimum variabel yang diizinkan yang akan ditambahkan.
• Jika <ThrowExceptionOnLimit> adalah true, data tidak dikirim ke Analytics dan sebagai gantinya error akan ditampilkan ke klien.

Topik terkait

• Kebijakan ExtractVariables