docs(samples): added samples and test to migrate key and get metrics (#…

…161)

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/python-recaptcha-enterprise/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

Fixes #160  🦕

recaptcha_enterprise/snippets/get_metrics.py

@@ -0,0 +1,47 @@
+# 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_get_metrics_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+
+def get_metrics(project_id: str, recaptcha_site_key: str) -> None:
+    """ Get metrics specific to a recaptcha site key.
+        E.g: score bucket count for a key or number of
+        times the checkbox key failed/ passed etc.,
+    Args:
+    project_id: Google Cloud Project ID.
+    recaptcha_site_key: Specify the site key to get metrics.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    metrics_name = f"projects/{project_id}/keys/{recaptcha_site_key}/metrics"
+    request = recaptchaenterprise_v1.GetMetricsRequest()
+    request.name = metrics_name
+
+    response = client.get_metrics(request)
+
+    # Retrieve the metrics you want from the key.
+    # If the site key is checkbox type: then use response.challenge_metrics
+    # instead of response.score_metrics
+    for day_metric in response.score_metrics:
+        # Each 'day_metric' is in the granularity of one day.
+        score_bucket_count = day_metric.overall_metrics.score_buckets
+        print(score_bucket_count)
+
+    print(f"Retrieved the bucket count for score based key: {recaptcha_site_key}")
+
+
+# [END recaptcha_enterprise_get_metrics_site_key]

recaptcha_enterprise/snippets/list_site_keys.py

@@ -15,8 +15,12 @@
 # [START recaptcha_enterprise_list_site_keys]
 from google.cloud import recaptchaenterprise_v1
 
+from google.cloud.recaptchaenterprise_v1.services.recaptcha_enterprise_service.pagers import (
+    ListKeysPager,
+)
 
-def list_site_keys(project_id: str) -> None:
+
+def list_site_keys(project_id: str) -> ListKeysPager:
     """ List all keys present under the given project ID.
 
     Args:
@@ -36,6 +40,8 @@ def list_site_keys(project_id: str) -> None:
     for i, key in enumerate(response):
         print(f"{str(i)}. {key.name}")
 
+    return response
+
 
 # [END recaptcha_enterprise_list_site_keys]
 

recaptcha_enterprise/snippets/migrate_site_key.py

@@ -0,0 +1,46 @@
+# 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_migrate_site_key]
+from google.cloud import recaptchaenterprise_v1
+
+from list_site_keys import list_site_keys
+
+
+def migrate_site_key(project_id: str, recaptcha_site_key: str) -> None:
+    """ Migrate a key from reCAPTCHA (non-Enterprise) to reCAPTCHA Enterprise.
+        If you created the key using Admin console: https://www.google.com/recaptcha/admin/site,
+        then use this API to migrate to reCAPTCHA Enterprise.
+        For more info, see: https://cloud.google.com/recaptcha-enterprise/docs/migrate-recaptcha
+    Args:
+    project_id: Google Cloud Project ID.
+    recaptcha_site_key: Specify the site key to migrate.
+    """
+
+    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()
+
+    # Specify the key name to migrate.
+    name = f"projects/{project_id}/keys/{recaptcha_site_key}"
+    request = recaptchaenterprise_v1.MigrateKeyRequest()
+    request.name = name
+
+    response = client.migrate_key(request)
+    # To verify if the site key has been migrated, use 'list_site_keys' to check if the
+    # key is present.
+    for key in list_site_keys(project_id):
+        if key.name == response.name:
+            print(f"Key migrated successfully: {recaptcha_site_key}")
+
+
+# [END recaptcha_enterprise_migrate_site_key]

recaptcha_enterprise/snippets/test_site_key.py

@@ -19,6 +19,7 @@
 
 from create_site_key import create_site_key
 from delete_site_key import delete_site_key
+from get_metrics import get_metrics
 from get_site_key import get_site_key
 from list_site_keys import list_site_keys
 from update_site_key import update_site_key
@@ -63,3 +64,11 @@ def test_update_site_key(capsys: CaptureFixture, recaptcha_site_key: str) -> Non
     )
     out, _ = capsys.readouterr()
     assert re.search("reCAPTCHA Site key successfully updated ! ", out)
+
+
+def test_get_metrics(capsys: CaptureFixture, recaptcha_site_key: str) -> None:
+    get_metrics(project_id=GOOGLE_CLOUD_PROJECT, recaptcha_site_key=recaptcha_site_key)
+    out, _ = capsys.readouterr()
+    assert re.search(
+        f"Retrieved the bucket count for score based key: {recaptcha_site_key}", out
+    )