设置 API 访问权限

以下说明介绍了如何通过 SDK 或 REST 设置对 Data Manager API 的访问权限。

前提条件

在使用 Data API 之前，请确保您已完成以下操作：

  1. Google Cloud 项目。
  2. 满足以下两个条件的 Google 账号：
    1. 在您填写数据管理器 API 意向表单后，已获准访问数据管理器 API。如果您能看到 API 产品详情页面，则表示您拥有访问权限。
    2. 拥有 Google Cloud 项目的 serviceusage.services.enable 权限，或者拥有包含该权限的角色。例如，roles/owner 和 roles/serviceusage.serviceUsageAdmin 都包含 serviceusage.services.enable 权限。如需查看您的权限，请参阅查看当前访问权限。

启用 API

如果您尚未启用 Data Manager API，请点击启用 Data Manager API，或按照说明手动执行此步骤。

启用 Data Manager API

如果您找不到 Data Manager API 或启用 Data Manager API 失败，请验证您的 Google 账号是否满足前提条件。

设置身份验证

除了 API 密钥之外，您还可以使用 Google 提供的任何身份验证方法。我们建议您查看为您的使用场景选择合适的身份验证方法，以确定哪种方法适合您的使用场景。

两种常见的身份验证方法是用户账号和服务账号：

  • 用户账号：代表直接与 Google API 和服务进行交互的人员。
  • 服务账号：代表应用（而非用户）作为用户。它们可让您的应用管理身份验证和授权。例如，如果应用需要访问 Google Cloud 资源。

您的集成可以使用应用默认凭据 (ADC) 从环境中自动查找凭据，这样您就不必更改客户端代码来进行身份验证。

选择用户账号或服务账号模拟来设置 ADC：

以下是使用用户账号凭据进行身份验证的步骤：

  1. 为您的项目配置 Google Auth Platform 设置。

    1. 在 Google Cloud 控制台中打开品牌推广页面。

    2. 选择您的项目。

    3. 填写表单，然后点击创建。

  2. 由于 Data Manager API 范围属于敏感范围，因此需要执行以下步骤：

    1. 前往项目的数据访问权限设置。

    2. 点击添加或移除范围。

    3. 在权限范围列表中，勾选 Data Manager API 旁边的复选框，然后点击更新。

    4. 点击保存。

    5. 前往 Google Cloud 控制台中的受众群体，然后更新发布状态和用户类型。如需详细了解这些设置，请参阅管理应用受众群体。

  3. 点击创建 OAuth2 客户端以在项目中创建 OAuth2 客户端，或按照说明创建桌面 OAuth2 客户端。

    创建 OAuth2 客户端

    在最后一步中，点击 DOWNLOAD CLIENT CONFIGURATION，并记下您选择的下载位置。

  4. 通过运行以下命令生成本地 ADC 文件。此命令会启动一个 Web 流程，系统会提示您登录与 API 搭配使用的 Google 账号。

    将 PATH_TO_CLIENT_JSON 替换为您下载的 JSON 文件的名称。

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"

  5. 使用以下命令确认凭据是否已正确设置。 如果成功，该命令会将访问令牌输出到控制台。

    gcloud auth application-default print-access-token

如需详细了解应用的身份验证和凭据，请参阅 Google 的身份验证方法和应用默认凭据的工作原理。

设置运营账号访问权限

向与您的用户账号关联的电子邮件地址授予对 Destination 的访问权限。

  • 如果使用的是 Google Ads 账号或数据合作伙伴账号，请按照说明将用户的电子邮件地址添加到相应账号。
  • 如果使用 Display & Video 360 账号，请按照说明将用户的电子邮件地址添加到该账号中。

设置相应编程语言的 SDK

在本地机器上，安装您选择的 SDK：

REST

  1. 将以下示例中的占位符（例如 OPERATING_ACCOUNT_PRODUCT、OPERATING_ACCOUNT_ID 和 AUDIENCE_ID）替换为您的账号和目标平台的值。
  2. 将 PROJECT_ID 替换为您的 Google Cloud ID。

  3. 将示例复制到命令行中以发送请求。

    如果您不是通过已建立的产品链接访问 operatingAccount，请移除 destinations 中条目的 linkedAccount 属性。

    #!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# Sends the request.
curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
  --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
  --header "x-goog-user-project: PROJECT_ID" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "product": "LOGIN_ACCOUNT_PRODUCT",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "product": "LINKED_ACCOUNT_PRODUCT",
        "accountId": "LINKED_ACCOUNT_ID"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
EOF

.NET

  1. 下载并解压缩 google-cloud-ads-datamanager-v1-csharp.tar.gz。

  2. 在您的 .NET 项目中，声明对 Data Manager API 库的 ProjectReference 依赖项。将 PATH_TO_CLIENT_LIBRARY 替换为从 google-cloud-ads-datamanager-v1-csharp.tar.gz 中提取 google-cloud-ads-datamanager-v1-csharp 目录的位置。

    <ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />

  3. 可选。获取实用程序库和代码示例。

    1. 下载并提取 data-manager-dotnet.tar.gz。

    2. 在您的 .NET 项目中，声明对实用程序库的 ProjectReference 依赖项。将 PATH_TO_UTILITY_LIBRARY 替换为从 data-manager-dotnet.tar.gz 中提取 data-manager-dotnet 目录的位置。

      <ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

    3. 如需格式化数据，请使用 .NET 项目中的 Formatter 实用程序。

    4. 浏览 samples 子目录中的代码示例。

      如需运行代码示例，请将 DATA_MANAGER_DOTNET_LIB 环境变量设置为您从 google-cloud-ads-datamanager-v1-csharp.tar.gz 中提取 google-cloud-ads-datamanager-v1-csharp 目录的位置。

      export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"

      切换到 samples 目录，并使用 dotnet run 获取可用示例的列表。

      dotnet run --framework net8.0

      运行示例时传递 --help 实参，以打印包含预期形参的用法语句。

      dotnet run --framework net8.0 -- ingest-audience-members --help

      为了帮助您开始使用一些示例数据，请使用 samples/sampledata/audience_members_1.csv 中的文件。

Java

  1. 下载并解压缩 google-cloud-ads-datamanager-v1-java.tar.gz。
  2. 进入 google-cloud-ads-datamanager-v1-java 目录。

  3. 运行以下命令，以构建库并将其发布到本地 Maven 代码库，以便与 Maven 或 Gradle 搭配使用。

    ./gradlew -Pversion=0.1.0 install

  4. 在 Java 项目中，声明对 Data Manager API 库的依赖项。

    Gradle：

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'

    Maven：

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.0</version>
</dependency>

  5. 可选。获取实用程序库和代码示例。

    1. 克隆 GitHub 代码库。

      git clone https://github.com/googleads/data-manager-java.git

    2. 进入 data-manager-java 目录。

    3. 构建实用程序库并将其发布到本地 Maven 代码库。

      ./gradlew data-manager-util:install

    4. 在 Java 项目中，声明对实用程序库的依赖项。

      Gradle：

      implementation 'com.google.api-ads:data-manager-util:0.1.0'

      Maven：

      <dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.1.0</version>
</dependency>

    5. 如需格式化和加密数据，请在 Java 项目中使用 UserDataFormatter 和 Encrypter 实用程序。

    6. 浏览 data-manager-samples 子目录中的代码示例或 GitHub 上的代码示例。 如需从命令行运行示例，请使用 Gradle run 任务。

      例如，以下命令会运行 IngestAudienceMembers 示例并输出使用情况语句：

      ./gradlew data-manager-samples:run \
  --args='IngestAudienceMembers --help'

      为了帮助您开始使用一些示例数据，请使用 data-manager-samples/src/main/resources/sampledata/audience_members_1.csv 中的文件。

Python

  1. 下载 ads-datamanager-v1-py.tar.gz。
  2. 前往下载目录。

  3. 运行以下命令来构建库，并使其可供同一 Python 环境中的其他项目使用：

    pip install ./ads-datamanager-v1-py.tar.gz

  4. 在 Python 项目中，声明对 Data Manager API 库的依赖项。 例如，如果您在项目中使用 requirements.txt 文件，请将以下行添加到该文件中：

    google-ads-data-manager=0.1.0

  5. 可选。获取实用程序库和代码示例。

    1. 下载并提取 data-manager-python.tar.gz。
    2. 进入 data-manager-python 目录。

    3. 如需在 Python 环境中安装实用程序库，请运行以下命令：

      pip install .

    4. 在 Python 项目中，声明对实用程序库的依赖项。例如，如果您在项目中使用 requirements.txt 文件，请将以下行添加到该文件中：

      google-ads-data-manager-util=0.1.0

    5. 如需格式化和加密数据，请使用 Python 项目中的 Formatter 和 Encrypter 实用程序。

    6. 浏览 samples 子目录中的代码示例。运行示例时传递 --help 实参，以打印包含预期形参的用法语句。

      为了帮助您开始使用一些示例数据，请使用 samples/sampledata/audience_members_1.csv 中的文件。

Node.js

  1. 下载并提取 ads-datamanager-v1-nodejs.tar.gz。
  2. 进入 ads-datamanager-v1-nodejs 目录。

  3. 运行以下命令，将库编译并打包到 .tgz 文件中，以便与 npm 搭配使用。

    npm install
npm pack

    这些命令会生成一个名为 google-cloud-datamanager-0.1.0.tgz 的归档。

  4. 在 Node.js 项目中，通过添加 google-cloud-datamanager-0.1.0.tgz 文件的完整路径和文件名的 dependencies 条目，声明对 Data Manager API 库的依赖项。

PHP

  1. 下载并解压缩 google-cloud-ads-datamanager-v1-php.tar.gz。
  2. 进入 google-cloud-ads-datamanager-v1-php 目录。

  3. 运行以下命令以解析库的依赖项：

    composer update --prefer-dist

  4. 在同一主机上 PHP 项目的 composer.json 文件中，按照以下步骤声明对 Data Manager API 库的依赖项：

    1. 添加一个指向 google-cloud-ads-datamanager-v1-php 目录位置的 repositories 部分。

      "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]

    2. 声明对 Data Manager API 库的依赖项。

      "require": {
   "googleads/data-manager": "^0.1.0"
}

  5. （可选）获取实用程序库和代码示例。

    1. 下载并提取 data-manager-php.tar.gz。
    2. 进入 data-manager-php 目录。

    3. 运行以下命令以解析库的依赖项：

      composer update --prefer-dist

    4. 在同一主机上 PHP 项目的 composer.json 文件中，按照以下步骤声明对实用程序库的依赖项：

      1. 在 repositories 部分中添加一个指向 data-manager-php 目录位置的条目。

        "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_UTILITY_LIBRARY"
   }
]

      2. 声明对实用程序库的依赖项。

        "require": {
   "googleads/data-manager-util": "@dev"
}

      如需格式化数据，请在 PHP 项目中使用 Formatter 实用程序。

    5. 浏览 samples 子目录中的代码示例。按照以下步骤运行示例：

      1. 进入 samples 目录。

      2. 将 DATA_MANAGER_PHP_LIB 环境变量设置为您提取客户端库的路径。

        export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"

      3. 运行以下命令以解析库的依赖项：

        composer update --prefer-dist

      4. 运行示例，并传递所有必需的实参。运行示例时传递 --help 实参，以打印包含预期形参的用法语句。

      为了帮助您开始使用一些示例数据，请使用 samples/sampledata/audience_members_1.csv 中的文件。

后续步骤