Reminder: v201705 will be sunset on May 31, 2018.

使用入门

开发者可以使用 DFP API 构建具有以下功能的应用:管理广告资源、创建订单、生成报表等。

DFP API 采用 SOAP 协议;为帮助您顺利开始使用,我们提供了 Java、.NET、Python、PHP 和 Ruby 语言的客户端库。要发出第一个 API 请求,请按照以下步骤操作。

获取对 DFP 广告联盟的访问权限

注册一个 DFP 帐号(如果您没有的话)。倘若您想在单独的环境中测试 API,则还可创建一个测试广告联盟。请注意,对于测试而言,您不需要使用 AdSense 帐号。

记录您的广告联盟代码。在登录您的广告联盟时,您会在网址中找到此代码。例如,在网址 https://www.google.com/dfp/2032576#delivery 中,2032576 即为您的广告联盟代码。

创建身份验证凭据

您必须使用 OAuth2 验证所有 DFP API 请求。以下步骤涵盖了有关访问您自己的 DFP 数据的简单使用情形。有关详情及其他选项,请参阅身份验证

  1. 打开 Google API 控制台凭据页面
  2. 从项目菜单中,选择创建项目,输入项目名称并视需要修改提供的项目 ID,然后点击创建
  3. 在“凭据”页面上,选择创建凭据,然后选择服务帐号密钥
  4. 选择新的服务帐号,然后选择 JSON 作为密钥类型。
  5. 点击创建以下载包含私钥的文件。

配置 DFP 广告联盟

  1. 转到 DFP 广告联盟
  2. 点击管理标签。
  3. 确保 API 访问权限已启用。
  4. 点击添加服务帐号用户按钮。
  5. 在表单中填写您在上一步中创建的服务帐号电子邮件。
  6. 点击保存按钮。此时,系统应该会显示一条消息,确认您的服务帐号已添加。

设置客户端

下载一个 DFP 客户端库。这种客户端库会提供封装容器函数和功能,有助于更方便快捷地开发应用。

下列标签简要介绍了如何使用拥有客户端库的各种语言进行编码。

Java

下面的基本示例展示了如何使用 Java 客户端库。如要了解更详细的使用情况信息,请参阅客户端库发布版中的 README 文件。

  1. 设置凭据

    在 Shell 中运行以下命令:

    curl https://raw.githubusercontent.com/googleads/googleads-java-lib/master/examples/dfp_axis/src/main/resources/ads.properties -o ~/ads.properties
    打开 ~/ads.properties 文件并填充以下字段:
    [...]
    api.dfp.applicationName=INSERT_APPLICATION_NAME_HERE
    api.dfp.jsonKeyPairPath=INSERT_PATH_TO_JSON_KEY_FILE_HERE
    api.dfp.networkCode=INSERT_NETWORK_CODE_HERE
    [...]
  2. 指定依赖关系

    修改您的 pom.xml 文件,并将以下内容添加到 dependencies 代码中。您可在 Github 上找到最新版本号。

    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>ads-lib</artifactId>
      <version>RELEASE</version>
    </dependency>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>dfp-axis</artifactId>
      <version>RELEASE</version>
    </dependency>
  3. 编写一些代码并发出请求!

    import com.google.api.ads.common.lib.auth.OfflineCredentials;
    import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
    import com.google.api.ads.dfp.axis.factory.DfpServices;
    import com.google.api.ads.dfp.axis.v201802.Network;
    import com.google.api.ads.dfp.axis.v201802.NetworkServiceInterface;
    import com.google.api.ads.dfp.lib.client.DfpSession;
    import com.google.api.client.auth.oauth2.Credential;
    
    public class App {
      public static void main(String[] args) throws Exception {
        Credential oAuth2Credential = new OfflineCredentials.Builder()
            .forApi(Api.DFP)
            .fromFile()
            .build()
            .generateCredential();
    
        // Construct a DfpSession.
        DfpSession session = new DfpSession.Builder()
            .fromFile()
            .withOAuth2Credential(oAuth2Credential)
            .build();
    
        // Construct a DFP service factory, which can only be used once per
        // thread, but should be reused as much as possible.
        DfpServices dfpServices = new DfpServices();
    
        // Retrieve the appropriate service
        NetworkServiceInterface networkService = dfpServices.get(session,
            NetworkServiceInterface.class);
    
        // Make a request
        Network network = networkService.getCurrentNetwork();
    
        System.out.printf("Current network has network code '%s' and display" +
            " name '%s'.%n", network.getNetworkCode(), network.getDisplayName());
      }
    }
    

Python

下面的基本示例展示了如何使用 Python 客户端库。Python 客户端库支持 Python 2.7 版或 Python 3.0 版及更高版本(借助 2to3 转换器)。如要了解更详细的使用情况信息,请参阅客户端库发布版中的 README 文件。

  1. 安装此库并设置凭据。

    在 Shell 中运行以下命令:

    pip install googleads
    curl https://raw.githubusercontent.com/googleads/googleads-python-lib/master/googleads.yaml -o ~/googleads.yaml
  2. 设置 ~/googleads.yaml 文件。

    填写以下字段:

    dfp:
      application_name: INSERT_APPLICATION_NAME_HERE
      network_code: INSERT_NETWORK_CODE_HERE
      path_to_private_key_file: INSERT_PATH_TO_FILE_HERE
    
  3. 运行一些代码并发出请求!
    # Import the library.
    from googleads import dfp
    
    # Initialize a client object, by default uses the credentials in ~/googleads.yaml.
    dfp_client = dfp.DfpClient.LoadFromStorage()
    
    # Initialize a service.
    network_service = dfp_client.GetService('NetworkService', version='v201802')
    
    # Make a request.
    current_network = network_service.getCurrentNetwork()
    
    print 'Found network %s (%s)!' % (current_network['displayName'],
                                      current_network['networkCode'])
    

PHP

下面的基本示例展示了如何使用 PHP 客户端库

  1. 安装此库并设置凭据。

    在 Shell 中运行以下命令来安装客户端库,并将 adsapi_php.ini 文件下载到您的主目录:

    composer require googleads/googleads-php-lib
    curl https://raw.githubusercontent.com/googleads/googleads-php-lib/master/examples/Dfp/adsapi_php.ini -o ~/adsapi_php.ini
  2. 设置 ~/adsapi_php.ini 文件。

    填写以下字段:

    [DFP]
    networkCode = "INSERT_NETWORK_CODE_HERE"
    applicationName = "INSERT_APPLICATION_NAME_HERE"
    
    [OAUTH2]
    jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
    scopes = "https://www.googleapis.com/auth/dfp"
    
  3. 运行一些代码并发出请求!
    <?php
    require 'vendor/autoload.php';
    use Google\AdsApi\Common\OAuth2TokenBuilder;
    use Google\AdsApi\Dfp\DfpServices;
    use Google\AdsApi\Dfp\DfpSession;
    use Google\AdsApi\Dfp\DfpSessionBuilder;
    use Google\AdsApi\Dfp\v201708\NetworkService;
    
    // Generate a refreshable OAuth2 credential for authentication.
    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->fromFile()
        ->build();
    // Construct an API session configured from a properties file and the OAuth2
    // credentials above.
    $session = (new DfpSessionBuilder())
        ->fromFile()
        ->withOAuth2Credential($oAuth2Credential)
        ->build();
    
    // Get a service.
    $dfpServices = new DfpServices();
    $networkService = $dfpServices->get($session, NetworkService::class);
    
    // Make a request
    $network = $networkService->getCurrentNetwork();
    printf(
        "Network with code %d and display name '%s' was found.\n",
        $network->getNetworkCode(),
        $network->getDisplayName()
    );
    

.NET

下面的基本示例展示了如何使用 .NET 客户端库

  1. 新建项目

    打开 Visual Studio 并创建新项目(即控制台应用)。

  2. 向项目中添加所需的库引用

    如果您使用的是 NuGet,则只需为 Google.DfpGoogle.Dfp.Examples.CSharp(若想运行代码示例)添加依赖项即可。

    否则,请从 GitHub 中下载二进制发布包,并将 \lib 文件夹中的所有 dll 复制到您的项目中。然后,将引用添加到您项目中的这些 dll 以及 System.Web.Services 中。

  3. 创建 App.config

    将“src\App.config”复制到项目目录,然后将它添加到您的项目中。如果您的应用有自己的 App.config,则您可以将以下节点复制到 App.config 中:

    • configuration/DfpApi
    • configuration/system.web
    • configuration/configSections/section[name="DfpApi"]
    • configuration/system.net
  4. 设置凭据

    打开 App.config 并修改以下键:

    <add key="ApplicationName" value="INSERT_YOUR_APPLICATION_NAME_HERE" />
    <add key="NetworkCode" value="INSERT_YOUR_NETWORK_CODE_HERE" />
    <add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
    <add key="OAuth2SecretsJsonPath" value="INSERT_OAUTH2_SECRETS_JSON_FILE_PATH_HERE" />
    
  5. 调用该库

    您可以调用该库,如下面的 C# 代码段所示

    DfpUser user = new DfpUser();
    using (InventoryService inventoryService =
        (InventoryService) dfpUser.GetService(DfpService.v201711.InventoryService)) {
    
      // Create a statement to select ad units.
      int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
      StatementBuilder statementBuilder = new StatementBuilder()
          .OrderBy("id ASC")
          .Limit(pageSize);
    
      // Retrieve a small amount of ad units at a time, paging through until all
      // ad units have been retrieved.
      int totalResultSetSize = 0;
      do {
        AdUnitPage page = inventoryService.getAdUnitsByStatement(
            statementBuilder.ToStatement());
    
        // Print out some information for each ad unit.
        if (page.results != null) {
          totalResultSetSize = page.totalResultSetSize;
          int i = page.startIndex;
          foreach (AdUnit adUnit in page.results) {
            Console.WriteLine(
                "{0}) Ad unit with ID \"{1}\" and name \"{2}\" was found.",
                i++,
                adUnit.id,
                adUnit.name
            );
          }
        }
    
        statementBuilder.IncreaseOffsetBy(pageSize);
      } while (statementBuilder.GetOffset() < totalResultSetSize);
    
      Console.WriteLine("Number of results found: {0}", totalResultSetSize);
    }
    

如果您不想在 App.config 中设置凭据,请参阅这篇 wiki 文章,了解 DfpUser 类的其他使用方法。要详细了解如何使用 .NET 客户端库,请参阅 README 文件。如果您想使用不含客户端库的 .NET 进行开发,请参阅这篇以 NoClientLibrary 为主题的 wiki 文章

Ruby

下面的基本示例展示了如何使用 Ruby 客户端库。Ruby 客户端库要求使用 Ruby 2.1 或更高版本。

  1. 安装 Ruby gem 并获取配置文件。

    在 Shell 中运行以下命令:

    gem install google-dfp-api
    curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/master/dfp_api/dfp_api.yml -o ~/dfp_api.yml
    
  2. 设置凭据

    填充 ~/dfp_api.yml 文件中的必填字段。如果您还没有 OAuth2 密钥文件,则需要按照相应步骤创建 OAuth2 凭据

    :authentication:
      :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
      :application_name: INSERT_APPLICATION_NAME_HERE
      :network_code: INSERT_NETWORK_CODE_HERE
    
  3. 编写一些代码并发出请求!
    # Import the library.
    require 'dfp_api'
    
    # Initialize a dfp client instance (uses credentials in ~/dfp_api.yml by default).
    dfp = DfpApi::Api.new
    
    # Get a service instance.
    network_service = dfp.service(:NetworkService, :v201802)
    
    # Make a request.
    network = network_service.get_current_network()
    
    puts "The current network is %s (%d)." %
            [network[:display_name], network[:network_code]]
    

您可在随 Ruby 客户端库一起发布的 README 文件中找到更详细的使用入门步骤。此外,请查看 Ruby 的完整示例库

后续步骤

如果您有一个运行良好的客户端库,那么尽可以根据自己的需要按照所提供的示例使用客户端库。

访问参考文档,详细了解 API。

如需获取帮助,请阅读“指南”部分中列出的高级主题,或访问论坛

发送以下问题的反馈:

此网页
DoubleClick for Publishers API
DoubleClick for Publishers API
需要帮助?请访问我们的支持页面