This document shows you how to migrate from the v1beta1
version to the v1
version of the reCAPTCHA Enterprise API.
If you are using v1beta1
to create and annotate assessments, we recommend
using v1
because the new features, such as reCAPTCHA
account defender, are available only on v1
. v1
supports both API key and
service account authentication.
To migrate your assessment calls from v1beta1
to v1
, do the following:
Replace calls to create assessments.
Replace
https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY
withhttps://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
Understand the changes in the assessment's JSON response:
When you use
v1
, thereasons
andscore
fields are encapsulated inriskAnalysis
in the response, and when you usev1beta1
, thereasons
andscore
fields are not encapsulated in the response.v1
{ "event":{ "expectedAction":"EXPECTED_ACTION", "hashedAccountId":"ACCOUNT_ID", "siteKey":"KEY_ID", "token":"TOKEN", "userAgent":"(USER-PROVIDED STRING)", "userIpAddress":"USER_PROVIDED_IP_ADDRESS" }, "name":"ASSESSMENT_ID", "riskAnalysis":{ "reasons":[], "score":"SCORE }, "tokenProperties":{ "action":"USER_INTERACTION", "createTime":"TIMESTAMP", "hostname":"HOSTNAME", "invalidReason":"(ENUM)", "valid":(BOOLEAN) } }
v1beta1
{ "event":{ "expectedAction":"EXPECTED_ACTION", "hashedAccountId":"ACCOUNT_ID", "siteKey":"KEY_ID", "token":"TOKEN", "userAgent":"(USER-PROVIDED STRING)", "userIpAddress":"USER_PROVIDED_IP_ADDRESS" }, "name":"ASSESSMENT_ID", "reasons":[], "score":"SCORE", "tokenProperties":{ "action":"USER_INTERACTION", "createTime":"TIMESTAMP", "hostname":"HOSTNAME", "invalidReason":"(ENUM)", "valid":(BOOLEAN) } }
Update your environment to use the
reasons
andscore
fields from the JSON response forv1
.The following sample code shows the fields that are used from the response of
v1
andv1beta1
:v1
..... ..... # Get the risk score and the reason(s) for reason in response.risk_analysis.reasons: print(reason) print( "The reCAPTCHA score for this token is: " + str(response.risk_analysis.score) ) .... ....
v1beta1
..... ..... # Get the risk score and the reason(s) for reason in response.reasons: print(reason) print( "The reCAPTCHA score for this token is: " + str(response.score) ) .... ....
Replace calls to annotate assessments.
Replace
https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments}:annotate
withhttps://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments}:annotate
If you are currently logging your
create
andannotate
API calls using audit logging it is recommended to use platform logging (available forv1
only).