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

Kebijakan pencatatan transaksi memungkinkan monetisasi untuk 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 Anda yang dimonetisasi akan dibagikan kepada developer aplikasi yang mengajukan permintaan. Pembagian keuntungan 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 dari suatu transaksi, sebagaimana berlaku. Opsi ini mendapatkan harga kotor atau bersih dari setelan yang Anda buat dalam kebijakan pencatatan transaksi.

Jika Anda menyiapkan paket kartu tarif, yang mengenakan biaya kepada developer untuk setiap transaksi, Anda dapat menetapkan tarif paket tersebut berdasarkan atribut khusus seperti jumlah byte yang dikirimkan dalam sebuah 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 menjadi tempat Anda mengenakan biaya paket tarif dasar).

Mengonfigurasi kebijakan pencatatan transaksi

Akses halaman Paket Produk, seperti yang dijelaskan di bawah.

Edge

Saat menambahkan paket produk API menggunakan UI Edge, Anda perlu mengonfigurasi kebijakan pencatatan transaksi dengan melakukan langkah-langkah berikut:

  1. Pilih produk API yang akan dikonfigurasi di bagian Kebijakan Pencatatan Transaksi (jika ada beberapa produk API dalam paket produk).
  2. Mengonfigurasi atribut transaksi.
  3. Mengonfigurasi atribut khusus.
  4. Tautkan referensi dengan ID transaksi unik.
  5. Mengonfigurasi pengembalian dana.
  6. Ulangi untuk setiap produk API yang ditentukan dalam paket produk API.

Edge Klasik (Private Cloud)

Untuk mengonfigurasi kebijakan perekaman transaksi menggunakan UI Edge Klasik:

  1. Login ke http://ms-ip:9000, dengan ms-ip yang merupakan alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih Publikasikan > Produk di menu navigasi atas.
  3. Klik + Transaction Recording Policy di baris untuk produk API yang berlaku. Jendela New Transaction Recording Policy akan ditampilkan.
  4. Konfigurasikan kebijakan pencatatan transaksi dengan melakukan langkah-langkah berikut:
  5. Klik Simpan.

Mengonfigurasi atribut transaksi

Di bagian Transaction Attributes, 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, 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 Kriteria Keberhasilan Transaksi. Konfigurasikan atribut Status dengan menentukan kolom berikut:
    Kolom Deskripsi
    Resource 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 Alur, 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 konfigurasikan 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 bagi hasil 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 yang wajib diisi bergantung pada dasar pembagian keuntungan. Misalnya, Anda dapat menyiapkan paket tarif bagi hasil yang didasarkan pada 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 tercatat 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 akan mendapatkan nilai variabel alur dari respons pesan dalam variabel bernama response.reason.phrase. Jika nilainya OK, dan kebijakan Pemeriksaan Batas Monetisasi disertakan ke 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 untuk disertakan dalam kebijakan pencatatan transaksi. Misalnya, jika Anda menyiapkan paket kartu tarif, yang mengenakan biaya kepada developer untuk setiap transaksi, Anda dapat menetapkan tarif paket tersebut berdasarkan atribut khusus seperti jumlah byte yang dikirimkan dalam transaksi. Selanjutnya, Anda harus menyertakan atribut khusus tersebut dalam kebijakan pencatatan transaksi.

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

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

Untuk mengonfigurasi atribut kustom, aktifkan tombol Use Custom Attributes dan tentukan hingga 10 atribut kustom. 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, Anda harus memberi nama 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).
Resource 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 Alur, 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 menyediakan 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 disediakan di kolom Panjang Konten HTTP, Anda harus menentukan Content-Length sebagai nilai.

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

  • Panggilan ke Reserve API yang memastikan bahwa pengguna prabayar memiliki kredit yang cukup untuk membeli produk dan mengalokasikan ("cadangan") dana untuk pembelian.
  • 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, solusi ini mengandalkan informasi yang Anda tentukan di bagian Menautkan Resource dengan ID Transaksi Unik.

Untuk mengonfigurasi atribut kustom, aktifkan tombol Use Unique Transaction IDs dan tautkan transaksi. Untuk setiap transaksi, Anda harus menentukan resource, lokasi respons, dan nilai atribut yang ditautkan dengan nilai terkait dalam transaksi lainnya.

Misalnya, panggilan API reservasi dan panggilan API biaya ditautkan sebagai berikut: kolom bernama session_id di header respons dari API cadangan 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 yang dimonetisasi. Transaksi dimonetisasi berdasarkan paket pendapatan bersama. Namun, anggaplah pengguna tidak puas dengan produk 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 pada kebijakan pencatatan transaksi.

Untuk mengonfigurasi pengembalian dana, aktifkan tombol Use refund Attributes dan tentukan detail pengembalian dana:

  1. Tentukan kriteria pengembalian dana dengan menentukan kolom berikut:
    Kolom Deskripsi
    Lokasi Respons Referensi 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, tidak memenuhi kriteria dalam ekspresi) akan 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 Alur, 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 Alur, 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 Optional Pengembalian Attributes dan konfigurasikan atributnya. Atribut pengembalian dana opsional sama dengan atribut transaksi opsional, seperti yang dijelaskan 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 menetapkan 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 didefinisikan oleh penyedia API.

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

Anda menambahkan atribut kebijakan pencatatan transaksi ke produk API dengan mengeluarkan 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. 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 mengeluarkan permintaan PUT ke API pengelolaan https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (dan bukan ke monetization API).

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 menetapkan atribut khusus untuk produk API yang biaya paket dasar Anda. Misalnya, jika Anda menyiapkan paket kartu tarif, yang membebankan biaya kepada developer untuk setiap transaksi, Anda dapat menetapkan tarif paket tersebut 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 dijadikan dasar tarif untuk paket tersebut. Namun, produk tertentu dalam paket tarif hanya dapat memiliki satu atribut khusus yang menjadi dasar tarif untuk paket tersebut.

Anda menetapkan atribut khusus sebagai atribut produk API. Lakukan hal ini dengan mengeluarkan 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 menentukan nama dan nilai atribut. Nama harus dalam format MINT_CUSTOM_ATTRIBUTE_{num}, dan {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