Mengonfigurasi kebijakan perekaman transaksi

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

Konfigurasikan kebijakan pencatatan transaksi untuk setiap produk API di paket produk API Anda, seperti yang dijelaskan di bagian berikut.

Pengantar

Dengan kebijakan pencatatan transaksi, monetisasi dapat menangkap parameter transaksi dan atribut khusus. Monetisasi memerlukan informasi ini untuk melakukan pemrosesan monetisasinya, seperti menerapkan paket tarif.

Misalnya, jika Anda menyiapkan paket tarif pembagian keuntungan, persentase pendapatan yang dihasilkan dari setiap transaksi yang melibatkan produk API yang dimonetisasi akan dibagikan kepada developer aplikasi yang membuat permintaan. Bagi hasil didasarkan pada harga bersih atau kotor transaksi (Anda menentukan yang mana), yaitu persentase dari harga kotor atau bersih setiap transaksi digunakan untuk menentukan pembagian keuntungan. Oleh karena itu, monetisasi perlu mengetahui harga kotor atau bersih suatu transaksi, sebagaimana berlaku. Metrik ini mendapatkan harga kotor atau bersih dari setelan yang Anda buat dalam kebijakan pencatatan transaksi.

Jika Anda menyiapkan paket kartu tarif dan menagih developer untuk setiap transaksi, Anda dapat menetapkan tarif paket berdasarkan atribut khusus, seperti jumlah byte yang dikirim dalam transaksi. Monetisasi perlu mengetahui apa itu atribut khusus dan di mana menemukannya. Jadi, Anda perlu menentukan atribut khusus dalam kebijakan pencatatan transaksi.

Selain menentukan atribut transaksi dalam kebijakan pencatatan transaksi, Anda dapat menentukan kriteria keberhasilan transaksi untuk menentukan kapan transaksi berhasil (untuk tujuan penagihan). Untuk contoh penetapan kriteria keberhasilan transaksi, lihat Contoh penetapan kriteria keberhasilan transaksi dalam kebijakan pencatatan transaksi. Anda juga dapat menentukan atribut khusus untuk produk API (yang Anda kenakan biaya paket dasar).

Mengonfigurasi kebijakan pencatatan transaksi

Akses halaman Paket Produk, seperti yang dijelaskan di bawah.

Mengonfigurasi atribut transaksi

Di bagian Atribut Transaksi, tentukan kriteria yang menunjukkan transaksi monetisasi yang berhasil.

1. Di kolom Transaction Success Criteria, tentukan ekspresi berdasarkan nilai atribut Status (dijelaskan berikutnya) untuk menentukan kapan transaksi berhasil (untuk tujuan penagihan). Transaksi yang tidak berhasil (yaitu, transaksi yang tidak memenuhi kriteria dalam ekspresi) akan dicatat, tetapi paket tarif tidak diterapkan ke transaksi tersebut. Contoh:

   txProviderStatus == 'OK'

2. Atribut Status berisi nilai yang digunakan oleh ekspresi yang dikonfigurasi di kolom Transaction Success Criteria. Konfigurasikan atribut Status dengan menentukan kolom berikut:

   Kolom	Deskripsi
   Referensi API	Pola URI yang ditentukan dalam produk API yang akan digunakan dalam mengidentifikasi transaksi yang dimonetisasi.
   Lokasi Respons	Lokasi respons tempat atribut ditentukan. Nilai yang valid mencakup: Variabel Flow, Header, Isi JSON, dan Isi XML.
   Nilai	Nilai respons. Untuk menentukan lebih dari satu nilai, klik + Tambahkan x (misalnya, + Tambahkan Variabel Alur).

3. Untuk mengonfigurasi atribut transaksi opsional, aktifkan tombol Use Optional Attributes dan konfigurasi atribut transaksi apa pun yang ditentukan dalam tabel berikut.

   Atribut	Deskripsi
   Harga kotor	Atribut ini hanya berlaku untuk paket tarif yang menggunakan model pembagian keuntungan. Untuk paket tarif tersebut, Harga Kotor atau Harga Bersih bersifat wajib. Pastikan nilai numerik dinyatakan sebagai jenis String. Harga kotor untuk transaksi. Untuk paket pembagian keuntungan, Anda perlu mencatat atribut Harga Kotor atau Harga Bersih. Atribut mana yang diperlukan bergantung pada dasar pembagian keuntungan. Misalnya, Anda dapat menyiapkan paket tarif pembagian keuntungan yang didasarkan pada harga kotor transaksi. Dalam hal ini, kolom Harga Kotor wajib diisi.
   Harga bersih	Atribut ini hanya berlaku untuk paket tarif yang menggunakan model pembagian keuntungan. Untuk paket tarif tersebut, Harga Kotor atau Harga Bersih bersifat wajib. Pastikan nilai numerik dinyatakan sebagai jenis String. Harga bersih untuk transaksi. Untuk rencana pembagian keuntungan, Anda perlu mencatat kolom Harga Bersih atau Harga Kotor. Kolom mana yang wajib diisi bergantung pada dasar pembagian keuntungan. Misalnya, Anda dapat menyiapkan paket tarif pembagian keuntungan berdasarkan harga bersih transaksi. Dalam hal ini, kolom Harga Bersih wajib diisi.
   Mata uang	Atribut ini diperlukan untuk paket tarif yang menggunakan model pembagian keuntungan. Jenis mata uang yang berlaku untuk transaksi.
   Kode Error	Kode error yang terkait dengan transaksi. Memberikan informasi lebih lanjut tentang transaksi yang gagal.
   Deskripsi Item	Deskripsi transaksi.
   Pajak	Atribut ini hanya relevan untuk model pembagian keuntungan dan hanya jika jumlah pajak dicatat dalam panggilan API. Pastikan nilai numerik dinyatakan sebagai jenis String. Jumlah pajak atas pembelian. Harga bersih ditambah pajak = harga kotor.

Misalnya, dengan menetapkan nilai berikut, monetisasi mendapatkan nilai variabel flow dari respons pesan dalam variabel yang disebut response.reason.phrase. Jika nilainya OK, dan kebijakan Pemeriksaan Batas Monetisasi disertakan pada permintaan ProxyEndpoint proxy API, monetisasi akan menghitungnya sebagai transaksi.

Kolom	Nilai
Kriteria Keberhasilan Transaksi	txProviderStatus == 'OK'
Status: Resource API	**
Status: Lokasi Respons	Variabel Alur
Status: Variabel Alur	response.reason.phrase

Mengonfigurasi atribut khusus

Di bagian Atribut Khusus, Anda mengidentifikasi atribut khusus yang akan disertakan dalam kebijakan pencatatan transaksi. Misalnya, jika Anda menyiapkan paket kartu tarif dan menagih developer untuk setiap transaksi, Anda dapat menetapkan tarif paket berdasarkan atribut khusus, seperti jumlah byte yang dikirim dalam sebuah transaksi. Selanjutnya, Anda harus menyertakan atribut khusus tersebut dalam kebijakan pencatatan transaksi.

Setiap atribut ini disimpan dalam log transaksi, yang dapat Anda kueri. Tarif ini juga ditampilkan saat Anda membuat paket tarif (sehingga Anda dapat memilih satu atau beberapa atribut ini yang akan menjadi dasar tarif untuk paket tersebut).

Anda dapat menyertakan atribut khusus yang ditetapkan dalam kebijakan pencatatan transaksi di laporan ringkasan pendapatan, seperti yang dijelaskan dalam Menyertakan atribut transaksi kustom dalam laporan ringkasan pendapatan.

Untuk mengonfigurasi atribut khusus, aktifkan tombol Use Custom Attributes dan tentukan hingga 10 atribut khusus. Untuk setiap atribut khusus yang Anda sertakan dalam kebijakan pencatatan transaksi, Anda harus menentukan informasi berikut.

Kolom	Deskripsi
Nama Atribut Khusus	Masukkan nama yang menjelaskan atribut khusus. Jika paket tarif didasarkan pada atribut khusus, nama ini akan ditampilkan kepada pengguna di detail paket tarif. Misalnya, jika atribut khusus menangkap durasi, berarti Anda harus menamai durasi atribut. Unit sebenarnya untuk atribut khusus (seperti jam, menit, atau detik) ditetapkan di kolom unit rating saat Anda membuat paket tarif atribut khusus (lihat Menentukan paket tarif dengan detail atribut khusus).
Referensi API	Pilih satu atau beberapa akhiran URI (yaitu, fragmen URI yang mengikuti jalur dasar) dari resource API yang diakses dalam transaksi. Resource yang tersedia sama seperti untuk atribut transaksi.
Lokasi Respons	Pilih lokasi dalam respons tempat atribut ditentukan. Nilai yang valid mencakup: Variabel Flow, Header, Isi JSON, dan Isi XML.
Nilai	Tentukan nilai untuk atribut khusus. Setiap nilai yang Anda tentukan sesuai dengan kolom, parameter, atau elemen konten yang memberikan atribut khusus di lokasi yang Anda tentukan. Untuk menentukan lebih dari satu nilai, klik + Tambahkan x (misalnya, + Tambahkan Variabel Alur). Misalnya, jika Anda mengonfigurasi atribut khusus bernama Panjang Konten dan memilih Header sebagai lokasi respons, jika nilai Panjang Konten diberikan di kolom Panjang Konten HTTP, Anda harus menentukan Content-Length sebagai nilai.

Tautkan resource dengan ID transaksi unik

Beberapa transaksi sederhana, melibatkan panggilan API ke satu resource. Namun, transaksi lainnya bisa lebih kompleks. Misalnya, transaksi untuk pembelian produk dalam aplikasi di aplikasi game seluler melibatkan beberapa panggilan resource:

• Panggilan ke API reservasi yang memastikan bahwa pengguna prabayar memiliki kredit yang cukup untuk membeli produk dan mengalokasikan ("mencadangkan") dana untuk pembelian tersebut.
• Panggilan ke API tagihan yang memotong dana dari akun pengguna prabayar.

Untuk memproses seluruh transaksi, monetisasi memerlukan cara untuk menautkan resource pertama (panggilan dan respons ke dan dari API cadangan) dengan resource kedua (panggilan dan respons ke dan dari API biaya). Untuk melakukannya, mengandalkan informasi yang Anda tentukan di bagian Menautkan Resource dengan ID Transaksi Unik.

Untuk mengonfigurasi atribut khusus, aktifkan tombol Gunakan ID Transaksi Unik dan tautkan transaksi. Untuk setiap transaksi, tentukan resource, lokasi respons, dan nilai atribut yang ditautkan dengan nilai terkait dalam transaksi lainnya.

Misalnya, panggilan API reservasi dan panggilan API tagihan ditautkan sebagai berikut: kolom bernama session_id dalam header respons dari API reservasi sesuai dengan header respons bernama reference_id dari API biaya. Dalam hal ini, Anda dapat menetapkan entri di bagian Menautkan Resource dengan ID Transaksi Unik sebagai berikut:

Resource	Lokasi respons	Nilai
reserve/{id}**	Header	session_id
/charge/{id}**	Header	reference_id

Mengonfigurasi pengembalian dana

Di bagian Pengembalian dana, Anda menentukan atribut yang digunakan monetisasi untuk memproses pengembalian dana.

Misalnya, pengguna membeli produk dari aplikasi seluler yang menggunakan API Anda yang dimonetisasi. Transaksi dimonetisasi berdasarkan paket pendapatan bersama. Namun, anggaplah pengguna tidak puas dengan produk tersebut dan ingin mengembalikannya. Jika dana produk dikembalikan menggunakan panggilan ke API Anda yang melakukan pengembalian dana, monetisasi akan melakukan penyesuaian monetisasi yang diperlukan. Hal ini dilakukan berdasarkan informasi yang Anda tentukan di bagian Pengembalian Dana dalam kebijakan pencatatan transaksi.

Untuk mengonfigurasi pengembalian dana, aktifkan tombol Gunakan Atribut Pengembalian Dana dan tentukan detail pengembalian dana:

1. Tentukan kriteria pengembalian dana dengan menentukan kolom berikut:

   Kolom	Deskripsi
   Lokasi Respons	Resource untuk transaksi pengembalian dana. Jika produk API menyediakan beberapa resource, Anda hanya dapat memilih resource yang melakukan pengembalian dana.
   Kriteria Keberhasilan Pengembalian Dana	Ekspresi berdasarkan nilai atribut Status (dijelaskan berikutnya) untuk menentukan kapan transaksi pengembalian dana berhasil (untuk tujuan penagihan). Transaksi pengembalian dana yang tidak berhasil (yaitu, transaksi tersebut tidak memenuhi kriteria dalam ekspresi) dicatat, tetapi paket tarif tidak diterapkan ke transaksi tersebut. Contoh: txProviderStatus == 'OK'

2. Konfigurasikan atribut Status dengan menentukan kolom berikut:

   Kolom	Deskripsi
   Lokasi Respons	Lokasi respons tempat atribut ditentukan. Nilai yang valid mencakup: Variabel Flow, Header, Isi JSON, dan Isi XML.
   Nilai	Nilai respons. Untuk menentukan lebih dari satu nilai, klik + Tambahkan x (misalnya, + Tambahkan Variabel Alur).

3. Konfigurasikan atribut Parent ID dengan menentukan kolom berikut:

   Kolom	Deskripsi
   Lokasi Respons	Lokasi respons tempat atribut ditentukan. Nilai yang valid mencakup: Variabel Flow, Header, Isi JSON, dan Isi XML.
   Nilai	ID transaksi yang pengembalian dananya diproses. Misalnya, jika pengguna membeli produk lalu meminta pengembalian dana, ID Transaksi Induk adalah ID transaksi pembelian. Untuk menentukan lebih dari satu nilai, klik + Tambahkan x (misalnya, + Tambahkan Variabel Alur).

4. Untuk mengonfigurasi atribut pengembalian dana opsional, aktifkan tombol Use Opsional Pengembalian Dana Atribut dan konfigurasikan atributnya. Atribut pengembalian dana opsional sama dengan atribut transaksi opsional, seperti yang ditentukan dalam Mengonfigurasi atribut transaksi.

Mengelola kebijakan pencatatan transaksi menggunakan API

Bagian berikut menjelaskan cara mengelola kebijakan pencatatan transaksi menggunakan API.

Membuat kebijakan pencatatan transaksi menggunakan API

Anda menentukan kebijakan pencatatan transaksi sebagai atribut produk API. Nilai atribut mengidentifikasi:

• Akhiran URI resource produk tempat kebijakan pencatatan transaksi dilampirkan. Akhiran menyertakan variabel pola yang diapit dalam tanda kurung kurawal. Variabel pola dievaluasi oleh Layanan API saat runtime. Misalnya, akhiran URI berikut menyertakan variabel pola {id}.

  /reserve/{id}**
  

  Dalam hal ini, Layanan API mengevaluasi akhiran URI resource sebagai /reserve diikuti dengan sub-direktori yang diawali dengan ID yang ditentukan oleh penyedia API.

• Resource yang merupakan respons tempat resource tersebut dilampirkan. Produk API dapat memiliki beberapa resource dan setiap resource dapat memiliki kebijakan pencatatan transaksi yang dilampirkan ke respons dari resource tersebut.
• Ekstrak variabel kebijakan yang memungkinkan kebijakan pencatatan transaksi untuk mengekstrak konten dari pesan respons untuk parameter transaksi yang ingin Anda ambil.

Anda menambahkan atribut kebijakan pencatatan transaksi ke produk API dengan mengajukan permintaan PUT ke API pengelolaan https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (dan bukan ke API monetisasi).

Menentukan kriteria keberhasilan transaksi menggunakan API

Anda dapat menentukan kriteria keberhasilan transaksi untuk menentukan kapan transaksi berhasil (untuk tujuan penagihan). Transaksi yang tidak berhasil (yaitu, transaksi tersebut memenuhi kriteria dalam ekspresi) akan dicatat, tetapi paket tarif tidak diterapkan ke transaksi tersebut. Untuk contoh penetapan kriteria keberhasilan transaksi, lihat Contoh penetapan kriteria keberhasilan transaksi dalam kebijakan pencatatan transaksi.

Anda menentukan kriteria keberhasilan transaksi sebagai atribut produk API. Lakukan hal ini dengan mengajukan permintaan PUT ke API pengelolaan https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (dan bukan ke API monetisasi).

Misalnya, dalam permintaan berikut, transaksi berhasil jika nilai txProviderStatus adalah success (spesifikasi terkait kriteria keberhasilan transaksi ditandai).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Menentukan atribut khusus menggunakan API

Anda dapat menentukan atribut khusus untuk produk API yang akan dikenakan biaya paket dasar. Misalnya, jika Anda menyiapkan paket kartu tarif dan menagih developer untuk setiap transaksi, Anda dapat menetapkan tarif paket berdasarkan atribut khusus, seperti jumlah byte yang dikirimkan dalam sebuah transaksi. Saat membuat paket tarif, Anda dapat menentukan satu atau beberapa atribut khusus yang akan menjadi dasar tarif untuk paket tersebut. Namun, produk tertentu dalam paket tarif hanya dapat memiliki satu atribut khusus yang akan menjadi dasar tarif untuk paket tersebut.

Anda menetapkan atribut khusus sebagai atribut produk API. Lakukan hal ini dengan mengajukan permintaan PUT ke API pengelolaan https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (dan bukan ke Monetization API).

Untuk setiap atribut khusus yang ditambahkan ke produk API, Anda harus menetapkan nama dan nilai atribut. Nama harus dalam format MINT_CUSTOM_ATTRIBUTE_{num}, dengan {num} merupakan bilangan bulat.

Misalnya, permintaan berikut menetapkan tiga atribut khusus.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Contoh penetapan kriteria keberhasilan transaksi dalam kebijakan pencatatan transaksi

Tabel berikut memberikan contoh transaksi yang berhasil dan gagal, berdasarkan ekspresi kriteria keberhasilan transaksi dan nilai txProviderStatus yang ditampilkan oleh proxy API. txProviderStatus adalah variabel internal yang digunakan monetisasi untuk menentukan keberhasilan transaksi.

Ekspresi kriteria keberhasilan	Ekspresi yang valid?	Nilai txProviderStatus dari proxy API	Hasil evaluasi
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	true	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus == 100"	true	"200"	false