以下說明如何透過 SDK 或 REST 設定 Data Manager API 的存取權。
必要條件
使用 Data API 前,請先確認下列事項:
- Google Cloud 專案。
- 符合下列兩項條件的 Google 帳戶:
- 填寫資料管理工具 API 意願表單後,已獲准存取資料管理工具 API。如果可以查看 API 產品詳細資料頁面,表示您有存取權。
- 在 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 和服務互動的使用者。
- 服務帳戶:代表應用程式 (而非使用者) 成為使用者。應用程式可透過這些 API 管理驗證和授權。舉例來說,如果應用程式需要存取 Google Cloud 資源。
您的整合項目可以使用應用程式預設憑證 (ADC),自動從環境中尋找憑證,因此您不必變更用戶端程式碼即可進行驗證。
選擇「使用者帳戶」或「服務帳戶模擬」來設定 ADC:
如要使用使用者帳戶憑證進行驗證,請按照下列步驟操作:
為專案設定 Google Auth Platform。
由於 Data Manager API 範圍屬於機密範圍,因此必須執行下列步驟:
按一下「新增或移除範圍」。
在範圍清單中,勾選「Data Manager API」旁的方塊,然後按一下「更新」。
按一下 [儲存]。
前往 Google Cloud 控制台的「Audience」(目標對象),然後更新「Publishing status」(發布狀態) 和「User type」(使用者類型)。如要進一步瞭解這些設定,請參閱「管理應用程式目標對象」。
按一下「建立 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": { "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
在 .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" />
(選用) 取得公用程式庫和程式碼範例。
下載並解壓縮 data-manager-dotnet.tar.gz。
在 .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" />
如要格式化資料,請在 .NET 專案中使用
Formatter
公用程式。瀏覽
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 -Pversion=0.1.0 install
在 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>
(選用) 取得公用程式庫和程式碼範例。
複製 GitHub 存放區。
git clone https://github.com/googleads/data-manager-java.git
前往
data-manager-java
目錄。建構公用程式庫,並發布至本機 Maven 存放區。
./gradlew data-manager-util:install
在 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>
如要格式化及加密資料,請在 Java 專案中使用
UserDataFormatter
和Encrypter
公用程式。瀏覽
data-manager-samples
子目錄中的程式碼範例,或 GitHub 上的程式碼範例。如要從指令列執行範例,請使用 Gradlerun
工作。舉例來說,下列指令會執行
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.0
(選用) 取得公用程式庫和程式碼範例。
- 下載並解壓縮 data-manager-python.tar.gz。
- 前往
data-manager-python
目錄。 如要在 Python 環境中安裝公用程式庫,請執行下列指令:
pip install .
在 Python 專案中,宣告公用程式庫的依附元件。舉例來說,如果專案使用
requirements.txt
檔案,請在檔案中新增下列程式碼:google-ads-data-manager-util=0.1.0
如要格式化及加密資料,請在 Python 專案中使用
Formatter
和Encrypter
公用程式。瀏覽
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.0.tgz
的封存檔。在 Node.js 專案中,為
google-cloud-datamanager-0.1.0.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 程式庫的依附元件:新增
repositories
區段,指向google-cloud-ads-datamanager-v1-php
目錄的位置。"repositories" : [ { "type" : "path", "url" : "PATH_TO_CLIENT_LIBRARY" } ]
宣告 Data Manager API 程式庫的依附元件。
"require": { "googleads/data-manager": "^0.1.0" }
(選用) 取得公用程式庫和程式碼範例。
- 下載並解壓縮 data-manager-php.tar.gz。
- 前往
data-manager-php
目錄。 執行下列指令,解決程式庫的依附元件問題:
composer update --prefer-dist
在同一主機上 PHP 專案的
composer.json
檔案中,按照下列步驟宣告公用程式庫的依附元件:在
repositories
區段中新增項目,指向data-manager-php
目錄的位置。"repositories" : [ { "type" : "path", "url" : "PATH_TO_UTILITY_LIBRARY" } ]
宣告公用程式庫的依附元件。
"require": { "googleads/data-manager-util": "@dev" }
如要設定資料格式,請在 PHP 專案中使用
Formatter
公用程式。瀏覽
samples
子目錄中的程式碼範例。按照下列步驟執行範例:前往
samples
目錄。將
DATA_MANAGER_PHP_LIB
環境變數設為您解壓縮用戶端程式庫的路徑。export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
執行下列指令,解決程式庫的依附元件問題:
composer update --prefer-dist
執行範例,並傳遞任何必要引數。執行範例時傳遞
--help
引數,即可列印用法陳述式和預期參數。
如要開始使用一些範例資料,請使用
samples/sampledata/audience_members_1.csv
中的檔案。