Membuat anotasi penilaian

Halaman ini menjelaskan cara memberikan masukan terkait akurasi penilaian yang dibuat oleh reCAPTCHA Enterprise. Dengan informasi ini, reCAPTCHA Enterprise dapat menyesuaikan model khusus situs Anda dan memberikan performa yang lebih baik untuk situs Anda dari waktu ke waktu.

Kapan harus membuat anotasi penilaian

reCAPTCHA Enterprise memberikan skor saat membuat penilaian yang membantu Anda memahami tingkat risiko yang ditimbulkan interaksi pengguna. Kemudian, ketika situs Anda memiliki lebih banyak informasi tentang interaksi pengguna untuk menentukan apakah interaksi tersebut sah atau menipu, Anda dapat mengonfirmasi atau memperbaiki penilaian reCAPTCHA Enterprise. Untuk melakukannya, kirimkan kembali ID penilaian reCAPTCHA ke Google yang diberi label sebagai LEGITIMATE atau FRAUDULENT. Mengonfirmasi atau mengoreksi penilaian reCAPTCHA Enterprise akan meningkatkan performa reCAPTCHA Enterprise untuk situs Anda.

Untuk meningkatkan performa reCAPTCHA Enterprise, Anda dapat mengonfirmasi anotasi untuk positif benar dan negatif benar selain anotasi untuk potensi error penilaian. Misalnya, untuk pengguna yang berhasil melakukan autentikasi menggunakan metode autentikasi 2 faktor dan menerima skor reCAPTCHA yang tinggi, Anda dapat menganotasi penilaian sebagai LEGITIMATE. Atau, jika skor reCAPTCHA rendah dan situs Anda menetapkan bahwa interaksi tersebut menipu atau disalahgunakan, Anda dapat menganotasi penilaian sebagai FRAUDULENT.

Daftar berikut menunjukkan informasi tambahan tentang beberapa contoh interaksi pengguna yang menunjukkan apakah interaksi pengguna sah atau menipu:

Penagihan balik kartu kredit atau bukti konkret penipuan lainnya menunjukkan bahwa transaksi keuangan sebelumnya merupakan penipuan.
Akun baru yang mengirim pesan yang ditandai sebagai spam oleh pengguna lain mungkin menunjukkan bahwa pembuatan akun tersebut bersifat menipu.
Kasus dukungan yang diajukan jika pengguna mengalami kesulitan login ke akunnya dapat menunjukkan bahwa upaya login tersebut sah.
Pembelian atau pemesanan di situs yang menggunakan reCAPTCHA Enterprise untuk melindungi dari scraping dapat menunjukkan bahwa pengguna tersebut sah.

Sebelum memulai

Pastikan Anda memiliki peran Identity and Access Management berikut: reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent).
Bergantung pada tempat Anda menyiapkan reCAPTCHA Enterprise, selesaikan langkah yang sesuai:
Buat penilaian untuk situs Anda.
Buat penilaian untuk aplikasi seluler Anda.
Siapkan integrasi WAF Anda.

Mengambil ID penilaian

Untuk menganotasi penilaian, ambil ID penilaian unik dengan cara berikut:

Untuk integrasi web dan seluler, Anda dapat mengambil ID penilaian unik dari respons penilaian.

Setelah membuat penilaian, Anda akan menerima respons JSON seperti yang ditunjukkan pada contoh berikut.

Ambil ID penilaian unik dari kolom name dalam respons JSON.

{
'tokenProperties': {
  'valid': True,
  'hostname': 'www.google.com',
  'action': 'homepage',
  'createTime': u'2019-03-28T12:24:17.894Z'
},
'riskAnalysis': {
  'score': 0.1,
  'reasons': ['AUTOMATION']
},
'event': {
  'token': 'RESPONSE_TOKEN',
  'siteKey': 'KEY_ID'
},
'name': 'ASSESSMENT_ID'
}

Untuk integrasi WAF, Anda dapat mengambil ID penilaian unik dari token reCAPTCHA. ID penilaian unik adalah string alfanumerik unik dari 16 karakter yang muncul di akhir token reCAPTCHA setelah :U=. Misalnya, jika token reCAPTFHA adalah .................U=6ZZZZe73fZZZZZZ0, ID penilaiannya adalah 6ZZZZe73fZZZZZZ0.

Membuat anotasi penilaian

Tentukan informasi dan label yang akan ditambahkan dalam isi JSON permintaan, bergantung pada kasus penggunaan Anda.

Tabel berikut mencantumkan label dan nilai yang dapat Anda gunakan untuk menganotasi peristiwa:

Label Deskripsi Contoh permintaan

Label	Deskripsi	Contoh permintaan
`reasons`	Opsional. Label untuk mendukung penilaian Anda. Berikan detail peristiwa real-time di label `reasons` dalam beberapa detik atau menit setelah peristiwa karena memengaruhi deteksi real-time. Untuk daftar kemungkinan nilai, lihat nilai alasan. Contoh: Untuk mendeteksi pengambilalihan akun, beri anotasi apakah sandi yang dimasukkan sudah benar dengan nilai `CORRECT_PASSWORD` atau `INCORRECT_PASSWORD`. Jika men-deploy MFA Anda sendiri, Anda dapat menambahkan nilai berikut: `INITIATED_TWO_FACTOR`, dan `PASSED_TWO_FACTOR` atau `FAILED_TWO_FACTOR`.	{ "reasons": ["INCORRECT_PASSWORD"] }
`annotation`	Opsional. Label untuk menunjukkan keabsahan penilaian. Berikan fakta tentang peristiwa login dan pendaftaran untuk memvalidasi atau memperbaiki penilaian risiko Anda di label `annotation`. Nilai yang mungkin: `LEGITIMATE` atau `FRAUDULENT`. Anda dapat mengirim informasi ini kapan saja atau sebagai bagian dari tugas batch. Namun, sebaiknya kirim informasi ini dalam beberapa detik atau menit setelah peristiwa karena akan memengaruhi deteksi real-time.	{ "annotation": "LEGITIMATE" }

reasons

Opsional. Label untuk mendukung penilaian Anda.

Berikan detail peristiwa real-time di label reasons dalam beberapa detik atau menit setelah peristiwa karena memengaruhi deteksi real-time.

Untuk daftar kemungkinan nilai, lihat nilai alasan.

Contoh: Untuk mendeteksi pengambilalihan akun, beri anotasi apakah sandi yang dimasukkan sudah benar dengan nilai CORRECT_PASSWORD atau INCORRECT_PASSWORD. Jika men-deploy MFA Anda sendiri, Anda dapat menambahkan nilai berikut: INITIATED_TWO_FACTOR, dan PASSED_TWO_FACTOR atau FAILED_TWO_FACTOR.


      {
      "reasons": ["INCORRECT_PASSWORD"]
      }

annotation

Opsional. Label untuk menunjukkan keabsahan penilaian.

Berikan fakta tentang peristiwa login dan pendaftaran untuk memvalidasi atau memperbaiki penilaian risiko Anda di label annotation.

Nilai yang mungkin: LEGITIMATE atau FRAUDULENT.

Anda dapat mengirim informasi ini kapan saja atau sebagai bagian dari tugas batch. Namun, sebaiknya kirim informasi ini dalam beberapa detik atau menit setelah peristiwa karena akan memengaruhi deteksi real-time.


      {
       "annotation": "LEGITIMATE"
      }

Anotasikan penilaian menggunakan metode projects.assessments.annotate dengan gcloud CLI atau kunci API.

Catatan: Jika Anda menggunakan API versi v1beta1, sebaiknya gunakan versi v1 karena fitur baru, seperti pelindung akun reCAPTCHA Enterprise hanya tersedia pada versi v1. Untuk bermigrasi dari v1beta1 ke v1, lihat Bermigrasi dari API v1beta ke API v1 .
gcloud CLI

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- ASSESSMENT_ID: Nilai kolom name yang ditampilkan dari panggilan projects.assessments.create
- ANNOTATION_LABEL: Label untuk menunjukkan apakah penilaian sah atau menipu. Nilai yang mungkin adalah LEGITIMATE atau FRAUDULENT.
- ANNOTATION_REASON: Menjelaskan konteks anotasi yang dipilih untuk penilaian ini. Untuk mempelajari kemungkinan nilai, lihat alasan untuk memberikan anotasi.
Metode HTTP dan URL:
```
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate
```
Isi JSON permintaan:
```
{
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}
```
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate"
PowerShell

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate" | Select-Object -Expand Content
Anda akan menerima kode status yang berhasil (2xx), serta respons yang kosong.
Kunci API

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- ASSESSMENT_ID: Nilai kolom name yang ditampilkan dari panggilan projects.assessments.create
- ANNOTATION_LABEL: Label untuk menunjukkan apakah penilaian sah atau menipu. Nilai yang mungkin adalah LEGITIMATE atau FRAUDULENT.
- ANNOTATION_REASON: Menjelaskan konteks anotasi yang dipilih untuk penilaian ini. Untuk mempelajari kemungkinan nilai, lihat alasan untuk memberikan anotasi.
Metode HTTP dan URL:
```
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
```
Isi JSON permintaan:
```
{
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}
```
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl

Catatan: Buat kunci API untuk melakukan autentikasi dengan API.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"
PowerShell

Catatan: Buat kunci API untuk melakukan autentikasi dengan API.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$headers = @{ }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content
Anda akan menerima kode status yang berhasil (2xx), serta respons yang kosong.

Langkah selanjutnya

Pelajari fitur perlindungan akun pengguna reCAPTCHA Enterprise.

Membuat anotasi penilaian

Kapan harus membuat anotasi penilaian

Sebelum memulai

Mengambil ID penilaian

Membuat anotasi penilaian

gcloud CLI

curl

PowerShell

Kunci API

curl

PowerShell

Langkah selanjutnya