Changes for library release v20.0.0 (#649)

Author: jradcliff

…basicoperations/GetArtifactMetadata.java …operations/SearchForGoogleAdsFields.javagoogle-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/GetArtifactMetadata.java renamed to google-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/SearchForGoogleAdsFields.java google-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/GetArtifactMetadata.java renamed to google-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/SearchForGoogleAdsFields.java

@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -23,34 +23,34 @@
 import com.google.ads.googleads.v11.resources.GoogleAdsField;
 import com.google.ads.googleads.v11.services.GoogleAdsFieldServiceClient;
 import com.google.ads.googleads.v11.services.GoogleAdsFieldServiceClient.SearchGoogleAdsFieldsPagedResponse;
-import com.google.common.collect.Lists;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
 /**
- * Gets the metadata, such as whether the artifact is selectable, filterable and sortable, of an
- * artifact. The artifact can be either a resource (such as customer, campaign) or a field (such as
- * metrics.impressions, campaign.id). It'll also show the data type and artifacts that are
- * selectable with the artifact.
+ * Searches for {@link GoogleAdsField}s that match a given prefix, retrieving metadata such as
+ * whether the field is selectable, filterable, or sortable, along with the data type and the fields
+ * that are selectable with the field. Each {@link GoogleAdsField} represents either a resource
+ * (such as {@code customer}, {@code campaign}) or a field (such as {@code metrics.impressions},
+ * {@code campaign.id}).
  */
-public class GetArtifactMetadata {
+public class SearchForGoogleAdsFields {
 
-  private static class GetArtifactMetadataParams extends CodeSampleParams {
+  private static class SearchForGoogleAdsFieldsParams extends CodeSampleParams {
 
-    @Parameter(names = ArgumentNames.ARTIFACT_NAME, required = true)
-    private String artifactName;
+    @Parameter(names = ArgumentNames.NAME_PREFIX, required = true)
+    private String namePrefix;
   }
 
   public static void main(String[] args) {
-    GetArtifactMetadataParams params = new GetArtifactMetadataParams();
+    SearchForGoogleAdsFieldsParams params = new SearchForGoogleAdsFieldsParams();
     if (!params.parseArguments(args)) {
 
       // Either pass the required parameters for this example on the command line, or insert them
       // into the code here. See the parameter class definition above for descriptions.
-      params.artifactName = "INSERT_ARTIFACT_NAME_HERE";
+      params.namePrefix = "INSERT_NAME_PREFIX_HERE";
     }
 
     GoogleAdsClient googleAdsClient = null;
@@ -66,7 +66,7 @@ public static void main(String[] args) {
     }
 
     try {
-      new GetArtifactMetadata().runExample(googleAdsClient, params.artifactName);
+      new SearchForGoogleAdsFields().runExample(googleAdsClient, params.namePrefix);
     } catch (GoogleAdsException gae) {
       // GoogleAdsException is the base class for most exceptions thrown by an API request.
       // Instances of this exception have a message and a GoogleAdsFailure that contains a
@@ -87,55 +87,58 @@ public static void main(String[] args) {
    * Runs the example.
    *
    * @param googleAdsClient the Google Ads API client.
-   * @param artifactName the name of artifact to get its metadata.
+   * @param namePrefix the name prefix to use in the query.
    * @throws GoogleAdsException if an API request failed with one or more service errors.
    */
-  private void runExample(GoogleAdsClient googleAdsClient, String artifactName) {
+  private void runExample(GoogleAdsClient googleAdsClient, String namePrefix) {
     try (GoogleAdsFieldServiceClient googleAdsFieldServiceClient =
         googleAdsClient.getLatestVersion().createGoogleAdsFieldServiceClient()) {
-      // Searches for an artifact whose name is the same as the specified artifactName.
+      // Searches for all fields whose name begins with the specified namePrefix.
       SearchGoogleAdsFieldsPagedResponse searchGoogleAdsFieldsPagedResponse =
           googleAdsFieldServiceClient.searchGoogleAdsFields(
               String.format(
-                  "SELECT name, category, selectable, filterable, sortable, selectable_with, "
-                      + "data_type, is_repeated WHERE name = '%s'",
-                  artifactName));
+                  "SELECT "
+                      + "name, "
+                      + "category, "
+                      + "selectable, "
+                      + "filterable, "
+                      + "sortable, "
+                      + "data_type, "
+                      + "is_repeated, "
+                      + "selectable_with "
+                      // The double "%%" below will produce a single "%" in the string returned by
+                      // String.format. A single "%" is the wildcard token in the Google Ads Query
+                      // language.
+                      + "WHERE name LIKE '%s%%'",
+                  namePrefix));
 
-      // Gets all returned artifacts and prints out their metadata.
-      List<GoogleAdsField> googleAdsFields =
-          Lists.newArrayList(searchGoogleAdsFieldsPagedResponse.iterateAll());
-      for (GoogleAdsField googleAdsField : googleAdsFields) {
+      if (searchGoogleAdsFieldsPagedResponse.getPage().getResponse().getTotalResultsCount() == 0) {
         System.out.printf(
-            "An artifact named '%s' with category '%s' and data type '%s' %s selectable, %s "
-                + "filterable, %s sortable and %s repeated.%n%n",
-            googleAdsField.getName(),
-            googleAdsField.getCategory(),
-            googleAdsField.getDataType(),
-            getIsOrIsNot(googleAdsField.getSelectable()),
-            getIsOrIsNot(googleAdsField.getFilterable()),
-            getIsOrIsNot(googleAdsField.getSortable()),
-            getIsOrIsNot(googleAdsField.getIsRepeated()));
+            "No GoogleAdsFields found with a name that begins with '%s'.%n", namePrefix);
+        return;
+      }
 
-        // Sorts the list of artifact names that are selectable with the specified artifact.
-        List<String> selectableArtifacts = new ArrayList(googleAdsField.getSelectableWithList());
-        Collections.sort(selectableArtifacts);
+      // Retrieves each matching GoogleAdsField and prints its metadata.
+      for (GoogleAdsField googleAdsField : searchGoogleAdsFieldsPagedResponse.iterateAll()) {
+        System.out.printf("%s:%n", googleAdsField.getName());
+        System.out.printf("  %-16s %s%n", "category:", googleAdsField.getCategory());
+        System.out.printf("  %-16s %s%n", "data type:", googleAdsField.getDataType());
+        System.out.printf("  %-16s %s%n", "selectable:", googleAdsField.getSelectable());
+        System.out.printf("  %-16s %s%n", "filterable:", googleAdsField.getFilterable());
+        System.out.printf("  %-16s %s%n", "sortable:", googleAdsField.getSortable());
+        System.out.printf("  %-16s %s%n", "repeated:", googleAdsField.getIsRepeated());
 
-        System.out.println("The artifact can be selected with the following artifacts:");
-        for (String selectableField : selectableArtifacts) {
-          System.out.println(selectableField);
+        // Prints the list of fields that are selectable with the field.
+        List<String> selectableWithFields = new ArrayList(googleAdsField.getSelectableWithList());
+        if (!selectableWithFields.isEmpty()) {
+          // Sorts and then prints the list.
+          Collections.sort(selectableWithFields);
+          System.out.printf("  %s%n", "selectable with:");
+          for (String selectableWithField : selectableWithFields) {
+            System.out.printf("    %s%n", selectableWithField);
+          }
         }
       }
-
-      if (googleAdsFields.isEmpty()) {
-        System.err.printf("The specified artifact '%s' doesn't exist.%n", artifactName);
-      }
     }
   }
-
-  /**
-   * Returns "is" when the specified value is true and "is not" when the specified value is false.
-   */
-  private String getIsOrIsNot(boolean value) {
-    return value ? "is" : "is not";
-  }
 }

google-ads-examples/src/main/java/com/google/ads/googleads/examples/utils/ArgumentNames.java

@@ -25,7 +25,6 @@ public final class ArgumentNames {
   public static final String ADJUSTMENT_DATE_TIME = "--adjustmentDateTime";
   public static final String ADJUSTMENT_TYPE = "--adjustmentType";
   public static final String ADVERTISER_UPLOAD_DATE_TIME = "--advertiserUploadDateTime";
-  public static final String ARTIFACT_NAME = "--artifactName";
   public static final String ASSET_GROUP_ID = "--assetGroupId";
   public static final String ATTRIBUTE_VALUE = "--attributeValue";
   public static final String AUDIENCE_ID = "--audienceId";
@@ -96,6 +95,7 @@ public final class ArgumentNames {
   public static final String MANAGER_ID = "--managerId";
   public static final String MARKETING_IMAGE_ASSET_ID = "--marketingImageAssetId";
   public static final String MERCHANT_CENTER_ACCOUNT_ID = "--merchantCenterAccountId";
+  public static final String NAME_PREFIX = "--namePrefix";
   public static final String OAUTH_CLIENT_FILE = "--oAuthClientFile";
   public static final String OAUTH_SCOPES = "--oAuthScopes";
   public static final String OFFLINE_USER_DATA_JOB_TYPE = "--offlineUserDataJobType";