docs(samples): added sample and tests for annotate assessment API

samples/snippets/annotate_assessment.py

@@ -0,0 +1,43 @@
+# Copyright 2021 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START recaptcha_enterprise_annotate_assessment]
+from google.cloud import recaptchaenterprise_v1
+
+
+def annotate_assessment(project_id: str, assessment_id: str) -> None:
+    """ Pre-requisite: Create an assessment before annotating.
+        Annotate an assessment to provide feedback on the correctness of recaptcha prediction.
+    Args:
+        project_id: GCloud Project ID
+        assessment_id: Value of the 'name' field returned from the create_assessment() call.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    assessment_name = f'projects/{project_id}/assessments/{assessment_id}'
+    # Build the annotation request.
+    # For more info on when/how to annotate, see:
+    # https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
+    request = recaptchaenterprise_v1.AnnotateAssessmentRequest()
+    request.name = assessment_name
+    request.annotation = request.Annotation.FRAUDULENT
+    request.reasons = [request.Reason.FAILED_TWO_FACTOR]
+
+    # Empty response is sent back.
+    client.annotate_assessment(request)
+    print('Annotated response sent successfully ! ')
+
+
+# [END recaptcha_enterprise_annotate_assessment]

samples/snippets/create_assessment.py

@@ -72,6 +72,7 @@ def create_assessment(
             "The reCAPTCHA score for this token is: "
             + str(response.risk_analysis.score)
         )
-
+        # Get the assessment name (id). Use this to annotate the assessment.
+        print("Assessment name: " + response.name.rsplit("/", maxsplit=1)[1].strip())
 
 # [END recaptcha_enterprise_create_assessment]

samples/snippets/requirements-test.txt

@@ -2,4 +2,5 @@ selenium==4.0.0; python_version > '3.6'
 selenium==3.141.0; python_version <= '3.6'
 Flask==2.0.2
 pytest==6.2.5
+pytest-dependency==0.5.1
 pytest-flask==1.2.0

samples/snippets/test_create_assessment.py

@@ -23,14 +23,15 @@
 from selenium import webdriver
 from selenium.webdriver.chrome.webdriver import WebDriver
 
-import create_assessment
-
-# TODO(developer): Replace these variables before running the sample.
+from annotate_assessment import annotate_assessment
+from create_assessment import create_assessment
 from create_site_key import create_site_key
 from delete_site_key import delete_site_key
 
+
 GOOGLE_CLOUD_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
 DOMAIN_NAME = "localhost"
+ASSESSMENT_NAME = ""
 
 
 @pytest.fixture(scope="session")
@@ -71,18 +72,32 @@ def recaptcha_site_key() -> str:
     )
 
 
+@pytest.mark.dependency()
 @pytest.mark.usefixtures("live_server")
 def test_create_assessment(
     capsys: CaptureFixture, recaptcha_site_key: str, browser: WebDriver
 ) -> None:
+    global ASSESSMENT_NAME
     token, action = get_token(recaptcha_site_key, browser)
     assess_token(recaptcha_site_key, token=token, action=action)
     out, _ = capsys.readouterr()
-    assert re.search("The reCAPTCHA score for this token is: ", out)
-    score = out.rsplit(":", maxsplit=1)[1].strip()
+    score = -1
+    for line in out.split("\n"):
+        if "The reCAPTCHA score for this token is" in line:
+            score = line.rsplit(":", maxsplit=1)[1].strip()
+        elif "Assessment name: " in line:
+            ASSESSMENT_NAME = line.rsplit(":", maxsplit=1)[1].strip()
+    assert score != -1 and ASSESSMENT_NAME != ""
     set_score(browser, score)
 
 
+@pytest.mark.dependency(depends=['test_create_assessment'])
+def test_annotate_assessment(capsys: CaptureFixture) -> None:
+    annotate_assessment(project_id=GOOGLE_CLOUD_PROJECT, assessment_id=ASSESSMENT_NAME)
+    out, _ = capsys.readouterr()
+    assert re.search("Annotated response sent successfully ! ", out)
+
+
 def get_token(recaptcha_site_key: str, browser: WebDriver) -> typing.Tuple:
     browser.get(url_for("assess", site_key=recaptcha_site_key, _external=True))
     time.sleep(5)
@@ -101,7 +116,7 @@ def get_token(recaptcha_site_key: str, browser: WebDriver) -> typing.Tuple:
 
 
 def assess_token(recaptcha_site_key: str, token: str, action: str) -> None:
-    create_assessment.create_assessment(
+    create_assessment(
         project_id=GOOGLE_CLOUD_PROJECT,
         recaptcha_site_key=recaptcha_site_key,
         token=token,