docs(samples): added samples and test for recaptcha key operations (#643)

* docs(samples): added samples and test for recaptcha key operations

* 🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* docs(samples): modified return type of ListSiteKey to be re-used in Migrate Key sample

* docs(samples): added comment

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: Sita04

recaptcha_enterprise/cloud-client/src/main/java/recaptcha/GetMetrics.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * 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.
+ */
+
+package recaptcha;
+
+// [START recaptcha_enterprise_get_metrics_site_key]
+
+import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
+import com.google.recaptchaenterprise.v1.GetMetricsRequest;
+import com.google.recaptchaenterprise.v1.Metrics;
+import com.google.recaptchaenterprise.v1.MetricsName;
+import com.google.recaptchaenterprise.v1.ScoreMetrics;
+import java.io.IOException;
+
+public class GetMetrics {
+
+  public static void main(String[] args) throws IOException {
+    String projectId = "project-id";
+    String recaptchaSiteKey = "recaptcha-site-key";
+
+    getMetrics(projectId, recaptchaSiteKey);
+  }
+
+  /**
+   * 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.,
+   *
+   * @param projectId: Google Cloud Project Id.
+   * @param recaptchaSiteKey: Specify the site key to get metrics.
+   */
+  public static void getMetrics(String projectId, String recaptchaSiteKey) throws IOException {
+    // Initialize client that will be used to send requests. This client only needs to be created
+    // once, and can be reused for multiple requests. After completing all of your requests, call
+    // the `client.close()` method on the client to safely
+    // clean up any remaining background resources.
+    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
+
+      GetMetricsRequest getMetricsRequest =
+          GetMetricsRequest.newBuilder()
+              .setName(MetricsName.of(projectId, recaptchaSiteKey).toString())
+              .build();
+
+      Metrics response = client.getMetrics(getMetricsRequest);
+
+      // Retrieve the metrics you want from the key.
+      // If the site key is checkbox type: then use response.getChallengeMetricsList() instead of
+      // response.getScoreMetricsList()
+      for (ScoreMetrics scoreMetrics : response.getScoreMetricsList()) {
+        // Each ScoreMetrics is in the granularity of one day.
+        int scoreBucketCount = scoreMetrics.getOverallMetrics().getScoreBucketsCount();
+        System.out.println(scoreBucketCount);
+      }
+      System.out.printf("Retrieved the bucket count for score based key: %s", recaptchaSiteKey);
+    }
+  }
+}
+// [END recaptcha_enterprise_get_metrics_site_key]

recaptcha_enterprise/cloud-client/src/main/java/recaptcha/ListSiteKeys.java

@@ -19,6 +19,7 @@
 // [START recaptcha_enterprise_list_site_keys]
 
 import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
+import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient.ListKeysPagedResponse;
 import com.google.recaptchaenterprise.v1.Key;
 import com.google.recaptchaenterprise.v1.ListKeysRequest;
 import com.google.recaptchaenterprise.v1.ProjectName;
@@ -36,9 +37,9 @@ public static void main(String[] args) throws IOException {
   /**
    * List all keys present under the given project ID.
    *
-   * @param projectID: GCloud Project ID.
+   * @param projectID : GCloud Project ID.
    */
-  public static void listSiteKeys(String projectID) throws IOException {
+  public static ListKeysPagedResponse listSiteKeys(String projectID) throws IOException {
     // Initialize client that will be used to send requests. This client only needs to be created
     // once, and can be reused for multiple requests. After completing all of your requests, call
     // the `client.close()` method on the client to safely
@@ -48,10 +49,12 @@ public static void listSiteKeys(String projectID) throws IOException {
       ListKeysRequest listKeysRequest =
           ListKeysRequest.newBuilder().setParent(ProjectName.of(projectID).toString()).build();
 
+      ListKeysPagedResponse response = client.listKeys(listKeysRequest);
       System.out.println("Listing reCAPTCHA site keys: ");
-      for (Key key : client.listKeys(listKeysRequest).iterateAll()) {
+      for (Key key : response.iterateAll()) {
         System.out.println(key.getName());
       }
+      return response;
     }
   }
 }

recaptcha_enterprise/cloud-client/src/main/java/recaptcha/MigrateKey.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * 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.
+ */
+
+package recaptcha;
+
+// [START recaptcha_enterprise_migrate_site_key]
+
+import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
+import com.google.recaptchaenterprise.v1.Key;
+import com.google.recaptchaenterprise.v1.KeyName;
+import com.google.recaptchaenterprise.v1.MigrateKeyRequest;
+import java.io.IOException;
+
+public class MigrateKey {
+
+  public static void main(String[] args) throws IOException {
+    String projectId = "project-id";
+    String recaptchaSiteKey = "recaptcha-site-key";
+
+    migrateKey(projectId, recaptchaSiteKey);
+  }
+
+  /**
+   * 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
+   *
+   * @param projectId: Google Cloud Project Id.
+   * @param recaptchaSiteKey: Specify the site key to migrate.
+   */
+  public static void migrateKey(String projectId, String recaptchaSiteKey) throws IOException {
+    // Initialize client that will be used to send requests. This client only needs to be created
+    // once, and can be reused for multiple requests. After completing all of your requests, call
+    // the `client.close()` method on the client to safely
+    // clean up any remaining background resources.
+    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
+
+      // Specify the key name to migrate.
+      MigrateKeyRequest migrateKeyRequest =
+          MigrateKeyRequest.newBuilder()
+              .setName(KeyName.of(projectId, recaptchaSiteKey).toString())
+              .build();
+
+      Key response = client.migrateKey(migrateKeyRequest);
+
+      // To verify if the site key has been migrated, use 'ListSiteKeys' and check if the
+      // key is present.
+      for (Key key : recaptcha.ListSiteKeys.listSiteKeys(projectId).iterateAll()) {
+        if (key.equals(response)) {
+          System.out.printf("Key migrated successfully: %s", recaptchaSiteKey);
+        }
+      }
+    }
+  }
+}
+// [END recaptcha_enterprise_migrate_site_key]

recaptcha_enterprise/cloud-client/src/test/java/app/SnippetsIT.java

@@ -50,6 +50,7 @@
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.web.util.UriComponentsBuilder;
 import recaptcha.AnnotateAssessment;
+import recaptcha.GetMetrics;
 
 @RunWith(SpringJUnit4ClassRunner.class)
 @EnableAutoConfiguration
@@ -73,7 +74,7 @@ public static void requireEnvVar(String envVarName) {
   }
 
   @BeforeClass
-  public static void setUp() throws IOException, InterruptedException, JSONException {
+  public static void setUp() throws IOException, InterruptedException {
     requireEnvVar("GOOGLE_APPLICATION_CREDENTIALS");
     requireEnvVar("GOOGLE_CLOUD_PROJECT");
 
@@ -162,6 +163,13 @@ public void testCreateAnnotateAssessment()
     assertThat(stdOut.toString()).contains("Annotated response sent successfully ! ");
   }
 
+  @Test
+  public void testGetMetrics() throws IOException {
+    GetMetrics.getMetrics(PROJECT_ID, RECAPTCHA_SITE_KEY_1);
+    assertThat(stdOut.toString())
+        .contains("Retrieved the bucket count for score based key: " + RECAPTCHA_SITE_KEY_1);
+  }
+
   public JSONObject createAssessment(String testURL)
       throws IOException, JSONException, InterruptedException {