Membuat anotasi penilaian

Halaman ini menjelaskan cara memberikan masukan tentang akurasi penilaian yang dibuat oleh Google Cloud Fraud Defense. Dengan informasi ini, Fraud Defense dapat menyesuaikan model spesifik situs Anda dan memberikan performa yang lebih baik untuk situs Anda seiring waktu.

Kapan harus membuat anotasi penilaian

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

Untuk meningkatkan performa Fraud Defense, Anda dapat mengonfirmasi anotasi untuk positif benar dan negatif benar selain anotasi untuk potensi kesalahan penilaian. Misalnya, untuk pengguna yang berhasil melakukan autentikasi menggunakan metode autentikasi 2 faktor dan menerima skor reCAPTCHA yang tinggi, Anda dapat memberi anotasi pada penilaian sebagai LEGITIMATE. Atau, jika skor Google Cloud Fraud Defense rendah dan situs Anda menentukan bahwa interaksi tersebut bersifat penipuan atau penyalahgunaan, Anda dapat memberi anotasi pada penilaian sebagai FRAUDULENT.

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

• Penagihan balik kartu kredit atau bukti konkret penipuan lainnya menunjukkan bahwa transaksi keuangan sebelumnya bersifat menipu.
• Akun baru yang mengirim pesan yang ditandai sebagai spam oleh pengguna lain mungkin mengindikasikan bahwa pembuatan akun tersebut bersifat menipu.
• Kasus dukungan yang diajukan jika pengguna mengalami kesulitan login ke akunnya mungkin menunjukkan bahwa upaya login tersebut sah.
• Pembelian atau pemesanan di situs yang menggunakan Fraud Defense untuk melindungi dari scraping mungkin 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 telah menyiapkan Fraud Defense, selesaikan langkah yang sesuai:

  • Buat penilaian untuk situs Anda.
  • Buat penilaian untuk aplikasi seluler Anda.
  • Siapkan integrasi WAF Anda.

Mengambil ID penilaian

Untuk memberi anotasi pada 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 yang terdiri dari 16 karakter yang muncul di akhir token reCAPTCHA setelah :U=. Misalnya, jika token reCAPTCHA adalah .................U=6ZZZZe73fZZZZZZ0, maka ID penilaiannya adalah 6ZZZZe73fZZZZZZ0.

Membuat anotasi penilaian

1. 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 memberi anotasi peristiwa:

   Label	Deskripsi	Contoh permintaan
   reasons	Opsional. Label untuk mendukung penilaian Anda. Berikan detail acara real-time dalam label reasons dalam beberapa detik atau menit setelah acara karena memengaruhi deteksi real-time. Untuk daftar kemungkinan nilai, lihat nilai alasan. Contoh: Untuk mendeteksi pengambilalihan akun, beri anotasi jika sandi yang dimasukkan benar dengan nilai CORRECT_PASSWORD atau INCORRECT_PASSWORD. Jika Anda 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 legitimasi penilaian. Berikan fakta tentang peristiwa login dan pendaftaran untuk memvalidasi atau mengoreksi penilaian risiko Anda di label annotation. Nilai yang mungkin: LEGITIMATE atau FRAUDULENT. Anda dapat mengirimkan informasi ini kapan saja atau sebagai bagian dari tugas batch. Namun, sebaiknya kirimkan informasi ini dalam beberapa detik atau menit setelah peristiwa karena informasi ini memengaruhi deteksi real-time.	{ "annotation": "LEGITIMATE" }

2. 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 Perlindungan akun hanya tersedia di versi v1. Untuk bermigrasi dari v1beta1 ke v1, lihat Bermigrasi dari v1 API beta ke v1 API .

   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 curang. Kemungkinan nilainya adalah LEGITIMATE atau FRAUDULENT.
   • ANNOTATION_REASON: Mendeskripsikan konteks untuk anotasi yang dipilih untuk penilaian ini. Untuk mempelajari kemungkinan nilai, lihat alasan untuk memberi anotasi pada penilaian.

   Metode HTTP dan URL:

   POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

   Meminta isi JSON:

   {
   "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 gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif 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/ASSESSMENT_ID:annotate"

   PowerShell

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif 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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

   Anda akan menerima kode status berhasil (2xx) dan respons 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 tersebut sah atau bersifat menipu. Kemungkinan nilainya adalah LEGITIMATE atau FRAUDULENT.
   • ANNOTATION_REASON: Mendeskripsikan konteks untuk anotasi yang dipilih untuk penilaian ini. Untuk mempelajari kemungkinan nilai, lihat alasan untuk menganotasi penilaian.

   Metode HTTP dan URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

   Meminta isi JSON:

   {
   "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 berhasil (2xx) dan respons kosong.

Langkah berikutnya

• Pelajari fitur perlindungan akun pengguna Fraud Defense.