本頁面由 Cloud Translation API 翻譯而成。

設定 API 存取權

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

必要條件

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

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

啟用 API

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

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

設定驗證方法

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

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

使用者帳戶：代表直接與 Google API 和服務互動的使用者。
服務帳戶：代表應用程式 (而非使用者) 成為使用者。應用程式可透過這些 API 管理驗證和授權。舉例來說，如果應用程式需要存取 Google Cloud 資源。

您的整合項目可以使用應用程式預設憑證 (ADC)，自動從環境中尋找憑證，因此您不必變更用戶端程式碼即可進行驗證。

選擇「使用者帳戶」或「服務帳戶模擬」來設定 ADC：

如要使用使用者帳戶憑證進行驗證，請按照下列步驟操作：

為專案設定 Google Auth Platform。

重要事項： 凡是取得 Data Manager API 範圍使用者憑證的 Google Cloud 應用程式，都必須通過 Google OAuth 驗證，以免使用者看到未經驗證的 UI 畫面。服務帳戶不需要進行 Google OAuth 驗證。
1. 在 Google Cloud 控制台中開啟「品牌」頁面。
2. 選取專案。
3. 填寫表單，然後按一下「建立」。
由於 Data Manager API 範圍屬於機密範圍，因此必須執行下列步驟：
1. 前往專案的「資料存取權」設定。
2. 按一下「新增或移除範圍」。
3. 在範圍清單中，勾選「Data Manager API」旁的方塊，然後按一下「更新」。
4. 按一下 [儲存]。
5. 前往 Google Cloud 控制台的「Audience」(目標對象)，然後更新「Publishing status」(發布狀態) 和「User type」(使用者類型)。如要進一步瞭解這些設定，請參閱「管理應用程式目標對象」。
按一下「建立 OAuth2 用戶端」，在專案中建立 OAuth2 用戶端，或按照操作說明建立「桌面」OAuth2 用戶端。

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

執行下列指令，產生本機 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"

使用下列指令確認憑證設定正確無誤。如果執行成功，指令會將存取權杖列印至控制台。
```
gcloud auth application-default print-access-token
```

如要進一步瞭解應用程式的驗證和憑證，請參閱「Google 的驗證方式」和「應用程式預設憑證的運作方式」。

設定營運帳戶存取權

授予與使用者帳戶相關聯的電子郵件地址存取權， Destination。

如果使用 Google Ads 或資料合作夥伴帳戶，請按照操作說明將使用者的電子郵件地址新增至帳戶。
如果使用 Display & Video 360 帳戶，請按照操作說明將使用者的電子郵件地址新增至帳戶。

為程式設計語言設定 SDK

在本機上安裝您選擇的 SDK：

REST

請在下列範例中更新預留位置，例如 OPERATING_ACCOUNT_PRODUCT、OPERATING_ACCOUNT_ID 和 AUDIENCE_ID，並填入您帳戶和目的地的相關值。
將 PROJECT_ID 替換為 Google Cloud 的 ID。

將範例複製到指令列，即可傳送要求。

如果不是透過已建立的產品連結存取 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

下載並解壓縮 google-cloud-ads-datamanager-v1-csharp.tar.gz。
在 .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" />
```
(選用) 取得公用程式庫和程式碼範例。
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

下載並解壓縮 google-cloud-ads-datamanager-v1-java.tar.gz。
前往 google-cloud-ads-datamanager-v1-java 目錄。
執行下列指令，建構程式庫並發布至本機 Maven 存放區，以便搭配 Maven 或 Gradle 使用。
```
./gradlew install
```

在 Java 專案中，宣告對 Data Manager API 程式庫的依附元件。

Gradle：

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

Maven：

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

(選用) 取得公用程式庫和程式碼範例。
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

下載 ads-datamanager-v1-py.tar.gz。
前往下載內容的目錄。
執行下列指令，建構程式庫並在相同 Python 環境中提供給其他專案：
```
pip install ./ads-datamanager-v1-py.tar.gz
```
在 Python 專案中，宣告 Data Manager API 程式庫的依附元件。舉例來說，如果您在專案中使用 requirements.txt 檔案，請在檔案中新增下列程式碼：
```
google-ads-data-manager=0.1.3
```
(選用) 取得公用程式庫和程式碼範例。
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

下載並解壓縮 ads-datamanager-v1-nodejs.tar.gz。
前往 ads-datamanager-v1-nodejs 目錄。
執行下列指令，將程式庫編譯並封裝成 .tgz 檔案，以便搭配 npm 使用。
```
npm install
npm pack
```
這些指令會產生名為 google-cloud-datamanager-0.1.3.tgz 的封存檔。
在 Node.js 專案中，為 google-cloud-datamanager-0.1.3.tgz 檔案的完整路徑和檔案名稱新增 dependencies 項目，藉此宣告 Data Manager API 程式庫的依附元件。

PHP

下載並解壓縮 google-cloud-ads-datamanager-v1-php.tar.gz。
前往 google-cloud-ads-datamanager-v1-php 目錄。
執行下列指令，解決程式庫的依附元件問題：
```
composer update --prefer-dist
```
在同一主機上 PHP 專案的 composer.json 檔案中，按照下列步驟宣告 Data Manager API 程式庫的依附元件：
1. 新增 repositories 區段，指向 google-cloud-ads-datamanager-v1-php 目錄的位置。
```
"repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]
```
2. 宣告 Data Manager API 程式庫的依附元件。
```
"require": {
   "googleads/data-manager": "0.1.3"
}
```
(選用) 取得公用程式庫和程式碼範例。
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 中的檔案。

後續步驟

進一步瞭解如何傳送目標對象資料。
進一步瞭解如何傳送事件。
參閱 REST 或 RPC 參考說明文件。