設定 API 存取權

以下說明如何使用 SDK 或 REST 設定 Data Manager API 的存取權。

必要條件

使用 Data API 前，請先確認下列事項：

  1. Google Cloud 專案。
  2. 在 Google Cloud 專案中具有 serviceusage.services.enable 權限的 Google 帳戶，或具有包含該權限的角色。舉例來說，roles/owner 和 roles/serviceusage.serviceUsageAdmin 都包含 serviceusage.services.enable 權限。如要查看權限，請參閱「查看目前的存取權」。
  3. 已安裝 Google Cloud 指令列介面。

啟用 API

如果尚未啟用 Data Manager API，請按一下「啟用 Data Manager API」，或按照操作說明手動執行這個步驟。

啟用 Data Manager API

如果找不到 Data Manager API 或無法啟用 Data Manager API，請確認您的 Google 帳戶符合必要條件。

設定驗證方法

除了 API 金鑰，您也可以使用Google 的任何驗證方法。建議您參閱「為您的用途選擇合適的驗證方法」，決定適合您用途的方法。

常見的驗證方法有使用者帳戶和服務帳戶：

  • 使用者帳戶：代表直接與 Google API 和服務互動的使用者。
  • 服務帳戶：代表應用程式 (而非使用者) 成為使用者。應用程式可透過這些 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 控制台的「Audience」(目標對象)，然後更新「Publishing status」(發布狀態) 和「User type」(使用者類型)。如要進一步瞭解這些設定，請參閱「管理應用程式目標對象」。

  3. 按一下「建立 OAuth2 用戶端」，在專案中建立 OAuth2 用戶端，或按照說明建立「桌面」OAuth2 用戶端。

    建立 OAuth2 用戶端

    在最後一個步驟中，按一下「下載用戶端設定」，並記下您選擇的下載位置。

  4. 執行下列指令，產生本機 ADC 檔案。這個指令會啟動網路流程，提示您登入 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 帳戶，請按照操作說明將使用者的電子郵件地址新增至帳戶。
  • 如果使用 Google Analytics 資源，請按照操作說明將使用者的電子郵件地址新增至帳戶。

為程式設計語言設定 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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "accountType": "LINKED_ACCOUNT_TYPE",
        "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

安裝用戶端程式庫

請按照 .NET 用戶端程式庫安裝指南中的操作說明，在專案中新增用戶端程式庫的依附元件。

選用：取得公用程式庫和程式碼範例。

  1. 複製 GitHub 存放區。

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

  2. 在 .NET 專案中，宣告公用程式庫的 ProjectReference 依附元件。將 PATH_TO_UTILITY_LIBRARY 替換為您複製 data-manager-dotnet 存放區的位置。

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

  3. 如要格式化資料，請在 .NET 專案中使用 Formatter 公用程式。

  4. 瀏覽 samples 子目錄中的程式碼範例，或前往 GitHub。

    切換至 samples 目錄，並使用 dotnet run 取得可用範例的清單。

    dotnet run

    執行範例時傳遞 --help 引數，即可列印用法陳述式和預期參數。

    dotnet run -- ingest-audience-members --help

    如要開始使用一些範例資料，請使用 samples/sampledata/audience_members_1.csv 中的檔案。

Java

安裝用戶端程式庫

如果您搭配使用 Maven 與 BOM，請將以下指令新增至 pom.xml 檔案：

  <dependencyManagement>
     <dependencies>
        <dependency>
           <groupId>com.google.cloud</groupId>
           <artifactId>libraries-bom</artifactId>
           <version>26.72.0</version>
           <type>pom</type>
           <scope>import</scope>
        </dependency>
        <dependency>
           <groupId>com.google.api-ads</groupId>
           <artifactId>data-manager-bom</artifactId>
           <version>0.1.0</version>
           <type>pom</type>
           <scope>import</scope>
        </dependency>
     </dependencies>
  </dependencyManagement>

  <dependencies>
     <dependency>
        <groupId>com.google.api-ads</groupId>
        <artifactId>data-manager</artifactId>
     </dependency>
  </dependencies>

如果您使用無 BOM 的 Maven，請在依附元件中加入以下指令：

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

如果您使用 Gradle 搭配 BOM，請在依附元件中加入以下指令：

  implementation platform('com.google.cloud:libraries-bom:26.72.0')
  implementation platform('com.google.api-ads:data-manager-bom:0.1.0')
  implementation 'com.google.api-ads:data-manager'

如果您使用無 BoM 的 Gradle，請在依附元件中加入以下指令：

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

如果您使用 SBT，請在依附元件中加入以下指令：

  libraryDependencies += "com.google.api-ads" % "data-manager" % "0.1.0"

選用：取得公用程式庫和程式碼範例。

  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.2.0'

    Maven：

    <dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.2.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 中的檔案。

Node.js

安裝用戶端程式庫

請按照 Node.js 用戶端程式庫安裝指南中的操作說明，在專案中將依附元件新增至 @google-ads/datamanager 用戶端程式庫。

選用：取得公用程式庫和程式碼範例。

  1. 複製 GitHub 存放區。

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

  2. 前往 data-manager-node 目錄。

  3. 執行下列指令來安裝依附元件。

    npm install

  4. 切換至 util 目錄。

    cd util

  5. 執行下列指令，將公用程式庫編譯並封裝到 .tgz 檔案中，以搭配 npm 使用。

    npm pack

    這個指令會產生名為 google-ads-datamanager-util-0.2.0.tgz 的封存檔。記下檔案位置，以便在後續步驟中使用。

  6. 在 Node.js 專案中，為 Data Manager API 公用程式庫宣告依附元件，方法是為 google-ads-datamanager-util-0.2.0.tgz 檔案的完整路徑和檔案名稱新增 dependencies 項目。

    {
   "dependencies": {
      ...
      "@google-ads/data-manager-util": "file:PATH_TO_UTILITY_LIBRARY/google-ads-datamanager-util-0.2.0.tgz",
      ...
   }
}

    如要格式化資料，請在 Node.js 專案中使用 UserDataFormatter 公用程式。

  7. 瀏覽 samples 子目錄中的程式碼範例，或 GitHub 上的程式碼範例。請按照下列步驟執行範例：

    1. 前往 data-manager-node 目錄。

    2. 執行範例，並傳遞任何必要引數。執行範例時傳遞 --help 引數，即可列印用法陳述式和預期參數。

      舉例來說，下列指令會執行 ingest_audience_members 範例，並列印用法陳述式：

      npm run ingest-audience-members -w samples -- --help

    如要開始使用一些範例資料，請使用 samples/sampledata/audience_members_1.csv 中的檔案。

PHP

安裝用戶端程式庫

按照 PHP 用戶端程式庫安裝指南中的操作說明，在專案中將依附元件新增至 googleads/data-manager 用戶端程式庫。

選用：取得公用程式庫和程式碼範例。

  1. 複製 GitHub 存放區。

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

  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 子目錄中的程式碼範例，或前往 GitHub。按照下列步驟執行範例：

    1. 前往 samples 目錄。

    2. 執行下列指令，解決程式庫的依附元件問題：

      composer update --prefer-dist

    3. 執行範例，並傳遞任何必要引數。執行範例時傳遞 --help 引數，即可列印用法陳述式和預期參數。

    如要開始使用一些範例資料，請使用 samples/sampledata/audience_members_1.csv 中的檔案。

Python

安裝用戶端程式庫

按照 Python 用戶端程式庫安裝指南中的操作說明，在專案中新增 google-ads-datamanager 用戶端程式庫的依附元件。

選用：取得公用程式庫和程式碼範例。

  1. 複製 GitHub 存放區。

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

  2. 前往 data-manager-python 目錄。

  3. 如要在 Python 環境中安裝公用程式庫，請執行下列指令：

    pip install .

  4. 在 Python 專案中，宣告公用程式庫的依附元件。舉例來說，如果專案使用 requirements.txt 檔案，請在檔案中新增下列程式碼：

    google-ads-data-manager-util=0.2.0

  5. 如要格式化及加密資料，請在 Python 專案中使用 Formatter 和 Encrypter 公用程式。

  6. 瀏覽 samples 子目錄中的程式碼範例，或前往 GitHub。如要執行範例，請安裝必要的依附元件：

    pip install .[samples]

    執行範例時傳遞 --help 引數，即可列印用法陳述式和預期參數。

    如要開始使用一些範例資料，請使用 samples/sampledata/audience_members_1.csv 中的檔案。

Ruby

安裝用戶端程式庫

按照 Ruby 用戶端程式庫安裝指南中的操作說明，在專案中新增用戶端程式庫的依附元件。

後續步驟