Reminder: v201611 will be sunset on November 30, 2017.

使用入门

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

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

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

请注册一个 DFP 广告管理系统(以下简称 DFP)帐号(如果您没有的话)。如果您希望在独立的环境中测试 API,还可以创建一个测试广告联盟

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

创建身份验证凭据

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

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

配置 DFP 广告联盟

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

设置客户端

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

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

Java

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

  1. 创建 Eclipse 项目

    打开 Eclipse,并按照相应说明来设置使用 Maven 的 Eclipse

  2. 设置凭据

    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
    [...]

    fromFile() 中的凭据和属性提取自 ads.properties 文件。有关详情,请参阅 README 文件。

    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.DFP)
        .fromFile()
        .build()
        .generateCredential();

    然后,您可以使用制作工具模式创建 DfpSession

    // Construct a DfpSession.
    DfpSession session = new DfpSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();
  3. 为 InventoryService 构建客户端

    您必须使用 SOAP 客户端存根才能调用 API。DfpServices 类负责处理此逻辑。由于构建此对象很耗资源,因此,请实例化此对象一次,然后在同一个线程中尽可能重复使用它。

    // 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();
    然后,您可以获取对服务类的引用,如下所示:
    InventoryServiceInterface inventoryService =
        dfpServices.get(session, InventoryServiceInterface.class);
  4. 执行操作

    通过实例化客户端以连接到 API 后,您便可以执行操作。下面的代码可将相应帐号中现有的所有广告单元都返回到 AdUnitPage 对象中。

    // Create a statement to select all ad units.
    StatementBuilder statementBuilder = new StatementBuilder()
        .orderBy("id ASC")
        .limit(StatementBuilder.SUGGESTED_PAGE_LIMIT);
    
    // Default for total result set size.
    int totalResultSetSize = 0;
    
    do {
      // Get ad units by statement.
      AdUnitPage page = inventoryService.getAdUnitsByStatement(statementBuilder.toStatement());
    
      if (page.getResults() != null) {
        totalResultSetSize = page.getTotalResultSetSize();
        int i = page.getStartIndex();
        for (AdUnit adUnit : page.getResults()) {
          System.out.printf(
              "%d) Ad unit with ID '%s' and name '%s' was found.%n", i++,
              adUnit.getId(), adUnit.getName());
        }
      }
    
      statementBuilder.increaseOffsetBy(StatementBuilder.SUGGESTED_PAGE_LIMIT);
    } while (statementBuilder.getOffset() < totalResultSetSize);
    
    System.out.printf("Number of results found: %d%n", totalResultSetSize);

要详细了解如何使用 Java 客户端库,请参阅客户端库发行版中的 README 文件。

Python

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

Python 客户端库支持 Python 2.7 版或 Python 3.0 版及更高版本(借助 2to3 转换器)。

您必须先按照与 Python 客户端库一起发布的 README 文件中的步骤执行操作,然后才能运行此示例。 如果您在对我们的客户端库进行身份验证的过程中需要帮助,则还必须按照 OAuth2 wiki 中的说明设置 OAuth2 凭据。

  1. 设置凭据

    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
    

    要初始化 Client 对象,请调用 DfpClient.LoadFromStorage(),以读取 googleads.yaml 文件中的字段。

    from googleads import dfp
    
    # Initialize client object.
    dfp_client = dfp.DfpClient.LoadFromStorage()
    
  2. 为 InventoryService 构建客户端

    每种服务都可以通过相应的 getService() 方法进行检索。getService() 方法会向相应的服务返回 SOAP 客户端。

    # Initialize appropriate service.
    ad_unit_service = client.GetService('InventoryService', version='v201705')
    
  3. 执行操作

    通过实例化客户端以连接到 API 后,您便可以执行操作。下面的代码会返回并输出广告联盟中现有的所有广告单元。

    statement = dfp.FilterStatement()
    
    # Retrieve a small amount of ad units at a time, paging
    # through until all ad units have been retrieved.
    while True:
      response = ad_unit_service.getAdUnitsByStatement(statement.ToStatement())
      if 'results' in response:
        for ad_unit in response['results']:
          # Print out some information for each ad unit.
          print('Ad unit with ID "%s" and name "%s" was found.\n' %
                (ad_unit['id'], ad_unit['name']))
        statement.offset += dfp.SUGGESTED_PAGE_LIMIT
      else:
        break
    
    print '\nNumber of results found: %s' % response['totalResultSetSize']

PHP

按照广告 PHP 客户端库 README 中的步骤开始使用。

.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();
    InventoryService inventoryService =
        (InventoryService) dfpUser.GetService(DfpService.v201705.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 客户端库,请参阅自述文件。如果您想使用不含客户端库的 .NET 进行开发,请参阅这篇以 NoClientLibrary 为主题的 wiki 文章

Ruby

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

Ruby 客户端库要求使用 Ruby 2.1 或 2.2 以及 1.0.0 或更新版的 Google 广告 Savon SOAP 工具包。

您必须先按照与 Ruby 客户端库一起发布的 README 文件中的步骤执行操作,然后才能运行此示例。您必须修改 dfp_api.yml 才能添加身份验证凭据。

  1. 设置凭据

    dfp_api.yml 文件复制到您的主目录并填充必填字段。

    [...]
    :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
    :application_name: INSERT_APPLICATION_NAME_HERE
    :network_code: INSERT_NETWORK_CODE_HERE
    [...]
    

    首先,创建一个新的 DfpApi 实例。此操作会从 ~/dfp_api.yml 文件加载凭据。有关指定凭据的备用方法,请参阅自述文件。

    # Get DfpApi instance and load configuration from ~/dfp_api.yml.
    dfp = DfpApi::Api.new
    
  2. 构建 InventoryService 实例

    每种服务都可通过 service() 方法进行检索。此方法可返回服务存根对象,该对象可用于调用自身方法。将服务名称指定为第一个参数,并将所需的 API 版本指定为第二个参数。

    inventory_service =
        dfp.service(:InventoryService, :v201705)
    
  3. 执行操作

    通过实例化客户端连接到 API 后,您便可以执行操作。下面的代码可将相应帐号中现有的所有广告单元都返回到 page 对象中(一次返回 500 个)。

    # Create a statement to select ad units.
    statement = DfpApi::FilterStatement.new()
    
    # Retrieve a small amount of ad units at a time, paging
    # through until all ad units have been retrieved.
    total_result_set_size = 0;
    begin
      page = inventory_service.get_ad_units_by_statement(
          statement.toStatement())
    
      # Print out some information for each ad unit.
      if page[:results]
        total_result_set_size = page[:total_result_set_size]
        page[:results].each_with_index do |ad_unit, index|
          puts "%d) Ad unit with ID '%s' and name '%s' was found." % [
              index + statement.offset,
              ad_unit[:id],
              ad_unit[:name]
          ]
        end
      end
      statement.offset += DfpApi::SUGGESTED_PAGE_LIMIT
    end while statement.offset < page[:total_result_set_size]
    
    puts 'Total number of ad units: %d' %
        total_result_set_size

如果您想使用不含客户端库的 Ruby 进行开发,请参阅这篇 wiki 文章

后续步骤

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

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

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

发送以下问题的反馈:

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