Merge pull request #36 from googleads/release-v0_5-d70c6cf9cbeb136e09d1

Changes for release v0_5.

google-ads-examples/src/main/java/com/google/ads/googleads/examples/accountmanagement/GetAccountChanges.java

@@ -0,0 +1,149 @@
+// Copyright 2018 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
+//
+//     https://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 com.google.ads.googleads.examples.accountmanagement;
+
+import com.beust.jcommander.Parameter;
+import com.google.ads.googleads.examples.utils.ArgumentNames;
+import com.google.ads.googleads.examples.utils.CodeSampleParams;
+import com.google.ads.googleads.lib.GoogleAdsClient;
+import com.google.ads.googleads.lib.GoogleAdsException;
+import com.google.ads.googleads.v0.errors.GoogleAdsError;
+import com.google.ads.googleads.v0.resources.ChangeStatus;
+import com.google.ads.googleads.v0.services.GoogleAdsRow;
+import com.google.ads.googleads.v0.services.GoogleAdsServiceClient;
+import com.google.ads.googleads.v0.services.GoogleAdsServiceClient.SearchPagedResponse;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.util.Optional;
+
+/** This example gets the changes in the account made in the last 7 days. */
+public class GetAccountChanges {
+
+  private static class GetAccountChangesParams extends CodeSampleParams {
+
+    @Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
+    private Long customerId;
+  }
+
+  public static void main(String[] args) {
+    GetAccountChangesParams params = new GetAccountChangesParams();
+    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.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
+    }
+
+    GoogleAdsClient googleAdsClient;
+    try {
+      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
+    } catch (FileNotFoundException fnfe) {
+      System.err.printf(
+          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
+      return;
+    } catch (IOException ioe) {
+      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
+      return;
+    }
+
+    try {
+      new GetAccountChanges().runExample(googleAdsClient, params.customerId);
+    } 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
+      // collection of GoogleAdsErrors that indicate the underlying causes of the
+      // GoogleAdsException.
+      System.err.printf(
+          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
+          gae.getRequestId());
+      int i = 0;
+      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
+        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
+      }
+    }
+  }
+
+  /**
+   * Runs the example.
+   *
+   * @param googleAdsClient the client instance.
+   * @param customerId the customerId for which to retrieve change status.
+   */
+  private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
+    String query =
+        "SELECT change_status.resource_name, "
+            + "change_status.last_change_date_time, "
+            + "change_status.resource_type, "
+            + "change_status.campaign, "
+            + "change_status.ad_group, "
+            + "change_status.resource_status, "
+            + "change_status.ad_group_ad, "
+            + "change_status.ad_group_criterion, "
+            + "change_status.campaign_criterion "
+            + "FROM change_status "
+            + "WHERE change_status.last_change_date_time DURING LAST_7_DAYS "
+            + "ORDER BY change_status.last_change_date_time";
+
+    try (GoogleAdsServiceClient client = googleAdsClient.getGoogleAdsServiceClient()) {
+      SearchPagedResponse response = client.search(String.valueOf(customerId), query);
+
+      for (GoogleAdsRow row : response.iterateAll()) {
+        Optional<String> resourceNameOfChangedEntity =
+            getResourceNameForResourceType(row.getChangeStatus());
+
+        System.out.printf(
+            "On '%s', change status '%s' shows a resource type of '%s' "
+                + "with resource name '%s' was '%s'.%n",
+            row.getChangeStatus().getLastChangeDateTime().getValue(),
+            row.getChangeStatus().getResourceName(),
+            row.getChangeStatus().getResourceType().name(),
+            resourceNameOfChangedEntity.orElse(""),
+            row.getChangeStatus().getResourceStatus().name());
+      }
+    }
+  }
+
+  /**
+   * Each returned row contains all possible changed fields. This function returns the resource name
+   * of the changed field based on the resource type. The changed field's parent is also populated
+   * but is not used.
+   *
+   * @param changeStatus the change status for which to get affected resource name.
+   * @return an Optional has a value when one could be obtained for the change resource type.
+   */
+  private static Optional<String> getResourceNameForResourceType(ChangeStatus changeStatus) {
+    String resourceName = null;
+    // This is the list of all known resource names but may be subject to change in the future.
+    // See https://developers.google.com/google-ads/api/docs/change-status for a description.
+    switch (changeStatus.getResourceType()) {
+      case AD_GROUP:
+        resourceName = changeStatus.getAdGroup().getValue();
+        break;
+      case AD_GROUP_AD:
+        resourceName = changeStatus.getAdGroupAd().getValue();
+        break;
+      case AD_GROUP_CRITERION:
+        resourceName = changeStatus.getAdGroup().getValue();
+        break;
+      case CAMPAIGN:
+        resourceName = changeStatus.getCampaign().getValue();
+        break;
+      case CAMPAIGN_CRITERION:
+        resourceName = changeStatus.getCampaignCriterion().getValue();
+        break;
+    }
+    return Optional.ofNullable(resourceName);
+  }
+}

google-ads-examples/src/main/java/com/google/ads/googleads/examples/billing/GetAccountBudgets.java

@@ -0,0 +1,146 @@
+// Copyright 2018 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
+//
+//     https://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 com.google.ads.googleads.examples.billing;
+
+import com.beust.jcommander.Parameter;
+import com.google.ads.googleads.examples.utils.ArgumentNames;
+import com.google.ads.googleads.examples.utils.CodeSampleParams;
+import com.google.ads.googleads.lib.GoogleAdsClient;
+import com.google.ads.googleads.lib.GoogleAdsException;
+import com.google.ads.googleads.v0.errors.GoogleAdsError;
+import com.google.ads.googleads.v0.resources.AccountBudget;
+import com.google.ads.googleads.v0.services.GoogleAdsRow;
+import com.google.ads.googleads.v0.services.GoogleAdsServiceClient;
+import com.google.ads.googleads.v0.services.GoogleAdsServiceClient.SearchPagedResponse;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+
+/** This example retrieves all account budgets for a Google Ads customer. */
+public class GetAccountBudgets {
+
+  private static class GetAccountBudgetParams extends CodeSampleParams {
+
+    @Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
+    private Long customerId;
+  }
+
+  public static void main(String[] args) {
+    GetAccountBudgetParams params = new GetAccountBudgetParams();
+    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.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
+    }
+
+    GoogleAdsClient googleAdsClient;
+    try {
+      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
+    } catch (FileNotFoundException fnfe) {
+      System.err.printf(
+          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
+      return;
+    } catch (IOException ioe) {
+      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
+      return;
+    }
+
+    try {
+      new GetAccountBudgets().runExample(googleAdsClient, params.customerId);
+    } 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
+      // collection of GoogleAdsErrors that indicate the underlying causes of the
+      // GoogleAdsException.
+      System.err.printf(
+          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
+          gae.getRequestId());
+      int i = 0;
+      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
+        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
+      }
+    }
+  }
+
+  /**
+   * Runs the example.
+   *
+   * @param googleAdsClient the Google Ads API client.
+   * @param customerId the customer ID for which to retrieve account budgets.
+   */
+  private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
+    String query =
+        "SELECT "
+            + "account_budget.status, "
+            + "account_budget.billing_setup, "
+            + "account_budget.approved_spending_limit_micros, "
+            + "account_budget.approved_spending_limit_type, "
+            + "account_budget.proposed_spending_limit_micros, "
+            + "account_budget.proposed_spending_limit_type, "
+            + "account_budget.approved_start_date_time, "
+            + "account_budget.proposed_start_date_time, "
+            + "account_budget.approved_end_date_time, "
+            + "account_budget.approved_end_time_type,"
+            + "account_budget.proposed_end_date_time, "
+            + "account_budget.proposed_end_time_type "
+            + "FROM account_budget";
+    try (GoogleAdsServiceClient googleAdsServiceClient =
+        googleAdsClient.getGoogleAdsServiceClient()) {
+      // Issues the search request.
+      SearchPagedResponse searchPagedResponse =
+          googleAdsServiceClient.search(Long.toString(customerId), query);
+
+      // Iterates over all rows in all pages and prints the requested field values for the account
+      // budget in each row.
+      for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) {
+        AccountBudget accountBudget = googleAdsRow.getAccountBudget();
+
+        System.out.printf(
+            "Account budget '%s' with "
+                + "status '%s' "
+                + "billing setup '%s' "
+                + "amount served %.2f "
+                + "total adjustments %.2f "
+                + "approved spending limit '%s' "
+                + "(proposed '%s') "
+                + "approved start time '%s' "
+                + "(proposed '%s') "
+                + "approved end time '%s' "
+                + "(proposed '%s')"
+                + ".%n",
+            accountBudget.getResourceName(),
+            accountBudget.getStatus(),
+            accountBudget.getBillingSetup().getValue(),
+            accountBudget.getAmountServedMicros().getValue() / 1_000_000.0,
+            accountBudget.getTotalAdjustmentsMicros().getValue() / 1_000_000.0,
+            accountBudget.hasApprovedSpendingLimitMicros()
+                ? String.format(
+                    "%.2f", accountBudget.getApprovedSpendingLimitMicros().getValue() / 1_000_000.0)
+                : accountBudget.getApprovedSpendingLimitType().name(),
+            accountBudget.hasProposedSpendingLimitMicros()
+                ? String.format(
+                    "%.2f", accountBudget.getProposedSpendingLimitMicros().getValue() / 1_000_000.0)
+                : accountBudget.getProposedSpendingLimitType().name(),
+            accountBudget.getApprovedStartDateTime().getValue(),
+            accountBudget.getProposedStartDateTime().getValue(),
+            accountBudget.hasApprovedEndDateTime()
+                ? accountBudget.getApprovedEndDateTime().getValue()
+                : accountBudget.getApprovedEndTimeType(),
+            accountBudget.hasProposedEndDateTime()
+                ? accountBudget.getProposedEndDateTime().getValue()
+                : accountBudget.getProposedEndTimeType());
+      }
+    }
+  }
+}

google-ads-examples/src/main/java/com/google/ads/googleads/examples/billing/GetBillingSetup.java

@@ -88,11 +88,12 @@ private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
     // Define a GAQL query to retrieve all billing setup information.
     String searchQuery = "SELECT billing_setup.id, "
         + "  billing_setup.status, "
-        + "  billing_setup.payments_account_id, "
-        + "  billing_setup.payments_account_name, "
-        + "  billing_setup.payments_profile_id, "
-        + "  billing_setup.payments_profile_name, "
-        + "  billing_setup.secondary_payments_profile_id "
+        + "  billing_setup.payments_account, "
+        + "  billing_setup.payments_account_info.payments_account_id, "
+        + "  billing_setup.payments_account_info.payments_account_name, "
+        + "  billing_setup.payments_account_info.payments_profile_id, "
+        + "  billing_setup.payments_account_info.payments_profile_name, "
+        + "  billing_setup.payments_account_info.secondary_payments_profile_id "
         + "FROM billing_setup";
 
     // Creates a request that will retrieve all billing setups using pages of the specified
@@ -113,18 +114,20 @@ private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
         System.out.printf(
             "Billing setup with ID '%d', "
                 + "status '%s', "
+                + "payments_account '%s', "
                 + "payments_account_id '%s', "
                 + "payments_account_name '%s', "
                 + "payments_profile_id '%s', "
                 + "payments_profile_name '%s', "
                 + "secondary_payments_profile_id '%s'.%n",
             billingSetup.getId().getValue(),
             billingSetup.getStatus(),
-            billingSetup.getPaymentsAccountId().getValue(),
-            billingSetup.getPaymentsAccountName().getValue(),
-            billingSetup.getPaymentsProfileId().getValue(),
-            billingSetup.getPaymentsProfileName().getValue(),
-            billingSetup.getSecondaryPaymentsProfileId().getValue());
+            billingSetup.getPaymentsAccount().getValue(),
+            billingSetup.getPaymentsAccountInfo().getPaymentsAccountId().getValue(),
+            billingSetup.getPaymentsAccountInfo().getPaymentsAccountName().getValue(),
+            billingSetup.getPaymentsAccountInfo().getPaymentsProfileId().getValue(),
+            billingSetup.getPaymentsAccountInfo().getPaymentsProfileName().getValue(),
+            billingSetup.getPaymentsAccountInfo().getSecondaryPaymentsProfileId().getValue());
       }
     }
   }