激励措施

本指南介绍了如何使用 Google Ads API 以编程方式为客户提取和应用 Google Ads 奖励。

提取激励

您可以使用 IncentiveService.FetchIncentive 方法来获取客户可获得的奖励。此方法可以返回个性化的“自选”奖励选项。

FetchIncentiveRequest 可以包括：

language_code：客户的语言代码（默认值为 en）。
country_code：客户的国家/地区代码（默认值为 US）。
email：客户的电子邮件地址。
type：要获取的激励的 IncentiveType。该 API 仅支持 ACQUISITION。

FetchIncentiveResponse 包含 IncentiveOffer。如果 OfferType 为 CYO_INCENTIVE，则 cyo_incentives 字段包含 low_offer、medium_offer 和 high_offer，每个字段都是一个 Incentive，其中包含 incentive_id、requirement 和 incentive_terms_and_conditions_url 等详细信息。

以下示例展示了如何获取奖励：

Java

// Copyright 2026 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.incentives;

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.v23.errors.GoogleAdsError;
import com.google.ads.googleads.v23.errors.GoogleAdsException;
import com.google.ads.googleads.v23.services.CyoIncentives;
import com.google.ads.googleads.v23.services.FetchIncentiveRequest;
import com.google.ads.googleads.v23.services.FetchIncentiveRequest.IncentiveType;
import com.google.ads.googleads.v23.services.FetchIncentiveResponse;
import com.google.ads.googleads.v23.services.Incentive;
import com.google.ads.googleads.v23.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example fetches the available incentives for a user.
 */
public class FetchIncentives {

  private static class FetchIncentivesParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.EMAIL_ADDRESS,
        required = true,
        description = "The email of the user to fetch incentives for.")
    private String email;

    @Parameter(
        names = ArgumentNames.LANGUAGE_CODE,
        description = "The language for the returned incentive.")
    private String languageCode = "en";

    @Parameter(
        names = ArgumentNames.COUNTRY_CODE,
        description = "The country for the returned incentive.")
    private String countryCode = "US";
  }

  public static void main(String[] args) throws IOException {
    FetchIncentivesParams params = new FetchIncentivesParams();
    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 more information.
      params.email = "INSERT_EMAIL_HERE";
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new FetchIncentives()
          .runExample(googleAdsClient, params.email, params.languageCode, params.countryCode);
    } 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 GoogleAdsError instances that detail the underlying causes of the
      // exception.
      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);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param email the email of the user to fetch incentives for.
   * @param languageCode the language of the incentives.
   * @param countryCode the country of the incentives.
   */
  private void runExample(
      GoogleAdsClient googleAdsClient, String email, String languageCode, String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient =
        googleAdsClient.getLatestVersion().createIncentiveServiceClient()) {
      FetchIncentiveRequest request = FetchIncentiveRequest.newBuilder().setCountryCode(countryCode)
          .setLanguageCode(languageCode).setEmail(email).setType(IncentiveType.ACQUISITION).build();

      // Issues the request.
      FetchIncentiveResponse response =
          incentiveServiceClient.fetchIncentive(request);

      // Processes the response.
      if (!response.hasIncentiveOffer()) {
        System.out.print("No incentive offer was found");
        return;
      }

      // If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be 3 incentives in the
      // response. At the time this example was written, all incentive offers are CYO incentive offers.
      if (response.getIncentiveOffer().hasCyoIncentives()) {
        CyoIncentives cyoIncentives = response.getIncentiveOffer().getCyoIncentives();
        printIncentiveDetails(cyoIncentives.getLowOffer());
        printIncentiveDetails(cyoIncentives.getMediumOffer());
        printIncentiveDetails(cyoIncentives.getHighOffer());
      }
    }
  }

  private void printIncentiveDetails(Incentive incentive) {
    System.out.println("====================================================================");
    System.out.printf("Incentive ID: '%s'%n", incentive.getIncentiveId());
    System.out.printf("Incentive requirement: '%s'%n", incentive.getRequirement());
    System.out.printf(
        "Incentive terms and conditions: '%s'%n", incentive.getIncentiveTermsAndConditionsUrl());
    System.out.println("====================================================================");
  }
}


FetchIncentives.java

C#

// Copyright 2026 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.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Lib;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V23.Errors;
using Google.Ads.GoogleAds.V23.Services;
using System;

using static Google.Ads.GoogleAds.V23.Services.FetchIncentiveRequest.Types;

namespace Google.Ads.GoogleAds.Examples.V23
{
    /// <summary>
    /// This code example fetches the available incentives for a user.
    /// </summary>
    public class FetchIncentives : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The email of the user to fetch incentives for.
            /// </summary>
            [Option("email", Required = true, HelpText =
                "The email of the user to fetch incentives for.")]
            public string Email { get; set; }

            /// <summary>
            /// The language for the returned incentive.
            /// </summary>
            [Option("languageCode", Required = true, HelpText =
                "The language for the returned incentive.")]
            public string LanguageCode { get; set; }

            /// <summary>
            /// The country for the returned incentive.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the returned incentive.")]
            public string CountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            FetchIncentives codeExample = new FetchIncentives();
            Console.WriteLine(codeExample.Description);
            codeExample.Run(new GoogleAdsClient(), options.Email,
            options.LanguageCode, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example fetches the available incentives for a user.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="email">The email of the user to fetch incentives for.</param>
        /// <param name="languageCode">The language for the returned incentive.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, string email, string languageCode,
            string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V23.IncentiveService);

            FetchIncentiveRequest request = new FetchIncentiveRequest()
            {
                CountryCode = countryCode,
                LanguageCode = languageCode,
                Email = email,
                Type = IncentiveType.Acquisition
            };

            try
            {
                FetchIncentiveResponse response =
                    incentiveService.FetchIncentive(request);

                if (response.IncentiveOffer.IsEmpty())
                {
                    Console.WriteLine("No incentive offer was found.");
                    return;
                }

                if (!response.IncentiveOffer.CyoIncentives.IsEmpty())
                {
                    CyoIncentives cyoIncentives = response.IncentiveOffer.CyoIncentives;
                    printIncentiveDetails(cyoIncentives.LowOffer);
                }

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }

        private void printIncentiveDetails(Incentive incentive)
        {
            Console.WriteLine("===========================================");
            Console.WriteLine($"Incentive ID: {incentive.IncentiveId}");
            Console.WriteLine($"Incentive requirement: {incentive.Requirement}");
            Console.WriteLine($"Incentive terms and conditions: {incentive.IncentiveTermsAndConditionsUrl}");
            Console.WriteLine("===========================================");
        }

    }
}FetchIncentives.cs

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

#!/usr/bin/env python
# Copyright 2025 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.
"""This example returns incentives for a given user.

To apply an incentive, use apply_incentive.py.
"""


import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v23.services import FetchIncentiveRequest, FetchIncentiveResponse
from google.ads.googleads.v23.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    email_address: str,
    language_code: str,
    country_code: str,
) -> None:
    """Returns incentives for a given user.

    Args:
        client: An initialized GoogleAdsClient instance.
        email_address: The email of the user to fetch incentives for.
        language_code: The language code of the user (e.g. 'en').
        country_code: The country code of the user (e.g. 'US').
    """
    incentive_service: IncentiveServiceClient = client.get_service(
        "IncentiveService"
    )
    fetch_incentive_request: FetchIncentiveRequest = client.get_type(
        "FetchIncentiveRequest"
    )

    fetch_incentive_request.email = email_address
    fetch_incentive_request.language_code = language_code
    fetch_incentive_request.country_code = country_code

    response: FetchIncentiveResponse = incentive_service.fetch_incentive(
        request=fetch_incentive_request
    )

    if response.incentive_offer and response.incentive_offer.cyo_incentives:
        print("Fetched incentive.")
        # If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be three
        # incentives in the response. At the time this example was written, all
        # incentive offers are CYO incentive offers.
        cyo_incentives = response.incentive_offer.cyo_incentives
        print(cyo_incentives.low_offer)
        print(cyo_incentives.medium_offer)
        print(cyo_incentives.high_offer)
    else:
        print("No incentives found.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Returns incentives for a given user."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-e",
        "--email_address",
        type=str,
        required=True,
        help="The email of the user to fetch incentives for.",
    )
    parser.add_argument(
        "-l",
        "--language_code",
        type=str,
        required=False,
        default="en",
        help="The language code of the user (e.g. 'en').",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=False,
        default="US",
        help="The country code of the user (e.g. 'US').",
    )
    args = parser.parse_args()

    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v23")

    try:
        main(
          googleads_client,
          args.email_address,
          args.language_code,
          args.country_code,
        )
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)
fetch_incentives.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

应用激励措施

客户选择奖励后，您可以使用 IncentiveService.ApplyIncentive 方法将其应用到特定的 Google Ads 客户账号。

ApplyIncentiveRequest 需要：

selected_incentive_id：客户选择的奖励的 ID。
customer_id：您应用奖励的账号的客户 ID。
country_code：客户的国家/地区代码，必须与 Google Ads 账号的结算国家/地区一致。

ApplyIncentiveResponse 会返回应用激励的 coupon_code 和 creation_time。

以下示例展示了如何应用激励：

Java

// Copyright 2026 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.incentives;

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.v23.errors.GoogleAdsError;
import com.google.ads.googleads.v23.errors.GoogleAdsException;
import com.google.ads.googleads.v23.services.ApplyIncentiveRequest;
import com.google.ads.googleads.v23.services.ApplyIncentiveResponse;
import com.google.ads.googleads.v23.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example applies an incentive to a user's account.
 *
 * <p>This example is a no-op if the user already has an accepted incentive. If the user attempts to
 * apply a new incentive, the response will simply return the existing incentive that has already
 * been applied to the account.
 */
public class ApplyIncentive {

  private static class ApplyIncentiveParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.CUSTOMER_ID,
        required = true,
        description = "The Google Ads customer ID.")
    private Long customerId;

    @Parameter(
        names = ArgumentNames.INCENTIVE_ID,
        required = true,
        description = "The ID of the incentive to apply.")
    private String incentiveId;

    @Parameter(
        names = ArgumentNames.COUNTRY_CODE,
        description = "The country for the incentive to apply.")
    private String countryCode = "US";
  }

  public static void main(String[] args) throws IOException {
    ApplyIncentiveParams params = new ApplyIncentiveParams();
    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 more information.
      params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
      params.incentiveId = "INSERT_INCENTIVE_ID_HERE";
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf("Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
          fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new ApplyIncentive().runExample(googleAdsClient, params.customerId, params.incentiveId,
          params.countryCode);
    } 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 GoogleAdsError instances that detail the underlying causes of the
      // exception.
      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);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param incentiveId the ID of the incentive to apply.
   * @param countryCode the country of the incentive.
   */
  private void runExample(GoogleAdsClient googleAdsClient, long customerId, String incentiveId,
      String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient = googleAdsClient.getLatestVersion()
        .createIncentiveServiceClient()) {
      ApplyIncentiveRequest request = ApplyIncentiveRequest.newBuilder()
          .setCustomerId(String.valueOf(customerId))
          .setSelectedIncentiveId(Long.parseLong(incentiveId)).setCountryCode(countryCode).build();
      // Issues the request.
      ApplyIncentiveResponse response = incentiveServiceClient.applyIncentive(request);

      // Processes the response.
      System.out.println("====================================================================");
      System.out.printf("Applied incentive with coupon code '%s'.%n", response.getCouponCode());
      System.out.printf("Incentive was created at '%s'.%n", response.getCreationTime());
      System.out.println("====================================================================");
    }
  }
}
ApplyIncentive.java

C#

// Copyright 2026 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.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Lib;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V23.Errors;
using Google.Ads.GoogleAds.V23.Services;
using System;

namespace Google.Ads.GoogleAds.Examples.V23
{
    /// <summary>
    /// This code example applies an incentive to a user's account.
    /// </summary>
    public class ApplyIncentive : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The customer ID for which the call is made.
            /// </summary>
            [Option("customerId", Required = true, HelpText =
                "The customer ID for which the call is made.")]
            public long CustomerId { get; set; }

            /// <summary>
            /// The ID of the incentive to apply.
            /// </summary>
            [Option("incentiveId", Required = true, HelpText =
                "The ID of the incentive to apply.")]
            public long IncentiveId { get; set; }

            /// <summary>
            /// The country for the incentive to apply.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the incentive to apply.")]
            public string CountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            ApplyIncentive codeExample = new ApplyIncentive();
            Console.WriteLine(codeExample.Description);              
            codeExample.Run(new GoogleAdsClient(), options.CustomerId,
            options.IncentiveId, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example applies an incentive to a user's account.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The client customer ID.</param>
        /// <param name="incentiveId">The ID of the incentive to apply.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, long customerId,
            long incentiveId, string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V23.IncentiveService);

            ApplyIncentiveRequest request = new ApplyIncentiveRequest()
            {
                CustomerId = customerId.ToString(),
                SelectedIncentiveId = incentiveId,
                CountryCode = countryCode
            };

            try
            {
                ApplyIncentiveResponse response =
                    incentiveService.ApplyIncentive(request);

                Console.WriteLine("===========================================");
                Console.WriteLine($"Applied incentive with coupon code: {response.CouponCode}");
                Console.WriteLine($"Incentive was created at: {response.CreationTime}");
                Console.WriteLine("===========================================");

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }
    }
}ApplyIncentive.cs

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

#!/usr/bin/env python
# Copyright 2025 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.
"""This example applies an incentive to a user's account.

This example is a no-op if the user already has an accepted incentive. If the
user attempts to apply a new incentive, the response will simply return the
existing incentive that has already been applied to the account. Use the
fetch_incentives.py example to get the available incentives.
"""


import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v23.services import ApplyIncentiveRequest, ApplyIncentiveResponse
from google.ads.googleads.v23.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    customer_id: str,
    incentive_id: str,
    country_code: str = None,
) -> None:
    """Applies an incentive for the ads customer.

    Args:
        client: An initialized GoogleAdsClient instance.
        customer_id: The client customer ID.
        country_code: The country code of the user.
        incentive_id: The incentive ID to select.
    """
    incentive_service: IncentiveServiceClient = client.get_service("IncentiveService")
    apply_incentive_request: ApplyIncentiveRequest = client.get_type(
        "ApplyIncentiveRequest"
    )

    apply_incentive_request.customer_id = customer_id
    apply_incentive_request.selected_incentive_id = incentive_id

    if country_code:
        apply_incentive_request.country_code = country_code

    response: ApplyIncentiveResponse = incentive_service.apply_incentive(
        request=apply_incentive_request
    )

    print("Applied incentive.")
    print(f"Coupon Code: {response.coupon_code}")
    print(f"Creation Time: {response.creation_time}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Applies an incentive for the ads customer."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-c",
        "--customer_id",
        type=str,
        required=True,
        help="The Google Ads customer ID.",
    )
    parser.add_argument(
        "-i",
        "--incentive_id",
        type=int,
        required=True,
        help="The incentive ID to select.",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=False,
        help="The country code of the user (e.g. 'US').",
    )
    args = parser.parse_args()

    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v23")

    try:
        main(
            googleads_client,
            args.customer_id,
            args.incentive_id,
            args.country_code,
        )
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)apply_incentive.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

检索已应用的激励

您可以通过 GoogleAdsService.Search 和 GoogleAdsService.SearchStream 查询只读 AppliedIncentive 资源，以检索有关已应用奖励的详细信息。

AppliedIncentive 中提供的主要字段包括：

resource_name
coupon_code
incentive_state
redemption_date_time
fulfillment_expiration_date_time
reward_grant_date_time
reward_expiration_date_time
currency_code
reward_amount_micros
granted_amount_micros
required_min_spend_micros
current_spend_towards_fulfillment_micros
reward_balance_remaining_micros

以下 GAQL 查询会从 AppliedIncentive 中提取所有字段：

SELECT
  applied_incentive.resource_name,
  applied_incentive.coupon_code,
  applied_incentive.incentive_state,
  applied_incentive.redemption_date_time,
  applied_incentive.fulfillment_expiration_date_time,
  applied_incentive.reward_grant_date_time,
  applied_incentive.reward_expiration_date_time,
  applied_incentive.currency_code,
  applied_incentive.reward_amount_micros,
  applied_incentive.granted_amount_micros,
  applied_incentive.required_min_spend_micros,
  applied_incentive.current_spend_towards_fulfillment_micros,
  applied_incentive.reward_balance_remaining_micros
FROM
  applied_incentive

账单

激励措施 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

提取激励

Java

C#

PHP

Python

Ruby

Perl

应用激励措施

Java

C#

PHP

Python

Ruby

Perl

检索已应用的激励

激励措施