Integrasi sisi server - Captcha - Alibaba Cloud Documentation Center

Setelah menyelesaikan integrasi sisi klien, panggil API VerifyIntelligentCaptcha dari server Anda untuk memvalidasi setiap tantangan CAPTCHA. Verifikasi sisi klien saja tidak melindungi aplikasi Anda—token dapat dipalsukan oleh penyerang dan harus divalidasi di backend sebelum permintaan diizinkan untuk dilanjutkan.

Prasyarat

Sebelum memulai, pastikan Anda telah:

Menyelesaikan integrasi sisi klien.
Membuat kredensial akses—Captcha 2.0 mendukung autentikasi AccessKey dan token Security Token Service (STS). Lihat Inisialisasi klien kredensial.
Memberikan izin AliyunYundunAFSFullAccess kepada pengguna Resource Access Management (RAM) yang memanggil API.

Penting

Jangan pernah menggunakan AccessKey akun root Alibaba Cloud Anda. Jika bocor, seluruh sumber daya cloud Anda berisiko. Gunakan AccessKey pengguna RAM sebagai gantinya.

Cara kerja

Verifikasi sisi server mengikuti alur berikut:

Klien menghasilkan token. Pengguna menyelesaikan tantangan CAPTCHA. SDK Captcha menghasilkan token CaptchaVerifyParam dari Konsol Captcha 2.0 dan meneruskannya ke server Anda.
Server Anda memanggil `VerifyIntelligentCaptcha`. Kirim token tersebut, tanpa modifikasi, ke layanan Captcha 2.0. Jangan pernah mengubah CaptchaVerifyParam—modifikasi apa pun menyebabkan error verifikasi.
Captcha 2.0 memberikan respons. API mengembalikan VerifyResult (true atau false) dan VerifyCode yang menjelaskan hasil spesifik.
Server Anda bertindak berdasarkan hasilnya. Izinkan permintaan jika VerifyResult bernilai true; tolak jika tidak.

Batasan token:

Setiap token hanya dapat diverifikasi satu kali. Penggunaan ulang mengembalikan F008.
Catatan inisialisasi kedaluwarsa setelah 20 menit. Jika interval antara inisialisasi dan verifikasi melebihi 20 menit, token tidak valid (F014).
Pada arsitektur V3, interval antara permintaan verifikasi perilaku dan permintaan verifikasi tanda tangan bisnis tidak boleh melebihi 90 detik (F019).

Instal SDK

Unduh SDK sisi server untuk bahasa pemrograman Anda dari OpenAPI Developer Portal. Ekstrak paket tersebut dan muat ke dalam proyek Anda.

Bahasa	URL unduh SDK	URL sumber Github
Java	Download Java SDK Download Java SDK (asynchronous)	Captcha SDK for Java Captcha SDK for Java-Async
Python	Download Python SDK	Captcha SDK for Python
TypeScript	Download TypeScript SDK	Captcha SDK for TypeScript
Go	Download Go SDK	Captcha SDK for Go
PHP	Download PHP SDK	Alibaba Cloud Green SDK for PHP
Swift	Download Swift SDK	Captcha SDK for Swift
C++	Download C++ SDK	Captcha SDK for C++
.NET	Download .NET SDK	Captcha SDK for .NET

Panggil API VerifyIntelligentCaptcha

Pilih titik akhir

Petakan nilai region dari AliyunCaptchaConfig sisi klien Anda ke titik akhir sisi server yang sesuai. Ketidaksesuaian wilayah menyebabkan error permintaan.

Nilai `region` klien	Penyebaran	Titik akhir sisi server
`cn`	Tiongkok daratan (Shanghai) — hanya IPv4	`captcha.cn-shanghai.aliyuncs.com`
`cn`	Tiongkok daratan (Shanghai) — dual-stack (IPv4 dan IPv6)	`captcha-dualstack.cn-shanghai.aliyuncs.com`
`sgp`	Di luar Tiongkok daratan (Singapura) — hanya IPv4	`captcha.ap-southeast-1.aliyuncs.com`
`sgp`	Di luar Tiongkok daratan (Singapura) — dual-stack (IPv4 dan IPv6)	`captcha-dualstack.ap-southeast-1.aliyuncs.com`

API menggunakan HTTPS dan metode POST.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`CaptchaVerifyParam`	String	Ya	Token yang dikembalikan oleh callback skrip Captcha. Teruskan ke API persis seperti diterima — jangan mengubahnya.
`SceneId`	String	Tidak	ID skenario untuk verifikasi saat ini. Tentukan ini di server Anda pada penerapan multi-skenario untuk mencegah klien mengganti skenario lain.

Format CaptchaVerifyParam berdasarkan arsitektur:

V2: {"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."}
V3: eyJjZXxxxxxxxxxxxxxxnVlfQ== (Base64-encoded)

Parameter respons

Parameter	Tipe	Deskripsi
`RequestId`	String	ID permintaan.
`Success`	Boolean	`true` jika pemanggilan API berhasil; `false` jika gagal.
`Code`	String	Kode respons tingkat HTTP.
`Message`	String	Detail tentang kode respons.
`VerifyResult`	Boolean	`true` jika tantangan CAPTCHA lolos; `false` jika gagal.
`VerifyCode`	String	Kode hasil verifikasi spesifik. Lihat tabel di bawah.
`CertifyID`	String	Pengidentifikasi epoch verifikasi. Jika Anda meneruskan `UserCertifyId` kustom selama inisialisasi, nilai tersebut dikembalikan di sini. Jika tidak, server menghasilkan `CertifyID` default.

Referensi VerifyCode

Periksa VerifyResult terlebih dahulu, lalu gunakan VerifyCode untuk diagnostik dan pencatatan log.

Kode	Makna	Tindakan
T001	Verifikasi berhasil.	Izinkan permintaan.
T005	Mode uji aktif dan dikonfigurasi untuk lolos semua verifikasi.	Di lingkungan produksi, periksa status kebijakan di Konsol Captcha 2.0. Lihat Konsol Captcha 2.0Panduan integrasi.
F001	Diduga serangan — diblokir oleh kebijakan pengendalian risiko.	Tolak permintaan.
F002	`CaptchaVerifyParam` kosong.	Periksa integrasi Anda: frontend harus meneruskan parameter ini ke server Anda tanpa modifikasi.
F003	`CaptchaVerifyParam` memiliki format tidak valid.	Periksa kode integrasi Anda — parameter tidak boleh diubah sebelum mencapai API.
F004	Mode uji aktif dan dikonfigurasi untuk memblokir semua verifikasi.	Login ke Konsol Captcha 2.0 dan sesuaikan status kebijakan untuk skenario ini. Lihat Konsol Captcha 2.0Kelola skenario.
F005	`sceneId` dalam `CaptchaVerifyParam` tidak valid.	Jangan ubah `CaptchaVerifyParam`. Periksa kode integrasi Anda.
F006	`sceneId` dalam `CaptchaVerifyParam` tidak termasuk dalam akun Anda.	Login ke Konsol Captcha 2.0 dan verifikasi konfigurasi skenario.
F008	Token digunakan ulang — token hanya dapat dikirimkan satu kali.	Minta pengguna menyelesaikan CAPTCHA lagi untuk mendapatkan token baru.
F009	Lingkungan perangkat virtual terdeteksi (VMware, VirtualBox, Hyper-V, Parallels, AVD, BlueStacks, atau browser desktop yang menyamar sebagai perangkat seluler).	Tolak permintaan, atau nonaktifkan pemeriksaan ini di Konsol Captcha 2.0 melalui kebijakan kustom. Lihat Konsol Captcha 2.0Konsol Captcha 2.0Konsol Captcha 2.0Konsol Captcha 2.0Atur kebijakan kustom.
F010	Frekuensi akses dari alamat IP yang sama melebihi batas.	Tolak permintaan. Sesuaikan ambang batas di Konsol Captcha 2.0 jika diperlukan. Lihat Atur kebijakan kustom.
F011	Frekuensi akses dari perangkat yang sama melebihi batas.	Tolak permintaan. Sesuaikan ambang batas di Konsol Captcha 2.0 jika diperlukan. Lihat Atur kebijakan kustom.
F012	`SceneId` dalam permintaan sisi server Anda tidak sesuai dengan `sceneId` yang dikonfigurasi di frontend.	Samakan `SceneId` sisi server Anda dengan skenario yang dikonfigurasi di Konsol Captcha.
F013	`CaptchaVerifyParam` tidak memiliki bidang yang diperlukan.	Jangan ubah `CaptchaVerifyParam`. Periksa kode integrasi Anda.
F014	Catatan inisialisasi tidak ditemukan.	Baik interval antara inisialisasi dan verifikasi melebihi 20 menit (mintalah klien melakukan inisialisasi ulang), atau tidak ada permintaan inisialisasi yang dikirim (periksa integrasi sisi klien Anda).
F015	Interaksi verifikasi gagal (misalnya, potongan puzzle tidak dipindahkan ke posisi yang benar).	Minta pengguna merefresh CAPTCHA dan mencoba lagi.
F016	Permintaan diblokir oleh kebijakan verifikasi URL yang dikonfigurasi di konsol.	Sesuaikan kebijakan verifikasi URL di Konsol Captcha 2.0. Lihat Atur kebijakan kustom.
F017	Diduga serangan — diblokir karena protokol atau parameter tidak normal.	Tolak permintaan.
F018	(Hanya V3) `CaptchaVerifyParam` untuk permintaan verifikasi tanda tangan bisnis sedang digunakan ulang.	Setiap permintaan verifikasi tanda tangan bisnis harus menggunakan token baru.
F019	(Hanya V3) Permintaan verifikasi tanda tangan bisnis dikirim lebih dari 90 detik setelah permintaan verifikasi perilaku, atau tanpa permintaan verifikasi perilaku sebelumnya.	Pastikan permintaan verifikasi tanda tangan bisnis mengikuti permintaan verifikasi perilaku dalam waktu 90 detik.
F020	(Hanya V3) `CaptchaVerifyParam` dari permintaan verifikasi tanda tangan bisnis tidak sesuai dengan ID skenario atau pengguna.	Periksa bahwa token yang digunakan untuk verifikasi tanda tangan bisnis sesuai dengan skenario dan pengguna yang benar.

Kode status HTTP

Status HTTP	Kode	Pesan
200	`Success`	Permintaan berhasil.
400	`MissingParameter`	Parameter yang diperlukan tidak tersedia.
401	`InvalidParameter`	Parameter tidak valid.
403	`Forbidden.AccountAccessDenied`	Tidak diizinkan. Layanan mungkin belum diaktifkan, atau akun Anda memiliki pembayaran tertunda.
403	`Forbidden.RAMUserAccessDenied`	Pengguna RAM tidak memiliki izin. Berikan izin AliyunYundunAFSFullAccess. Lihat Berikan izin kepada Peran RAM.
500	`InternalError`	Terjadi kesalahan internal. Ulangi permintaan.

Contoh kode

Untuk contoh verifikasi sisi server lengkap yang dapat dijalankan dalam semua bahasa yang didukung, lihat Kode contoh untuk verifikasi cerdas sisi server di OpenAPI Developer Portal.

Langkah berikutnya

Kelola skenario — buat dan konfigurasikan skenario untuk konteks verifikasi berbeda.
Atur kebijakan kustom — sesuaikan batas frekuensi, pendeteksian perangkat virtual, dan aturan verifikasi URL.