ID
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
大多數 Google Ads 實體都會公開 getId()
方法,傳回其 ID。雖然在大多數情況下並非必要,但 ID 可能在以下情況派上用場:
- 使用報表
- ID 是將報表列連結至實際 Google Ads 實體的絕佳方式。
- 維護外部資料儲存空間的對應
- 您可能已在自己的資料庫中儲存以 ID 為準的資訊。
- 想要稍微提升成效
按編號擷取通常比其他方式來得快,擷取單一實體的程式碼也比較簡單:
let campaigns = AdsApp.campaigns()
.withIds([678678])
.get();
// versus
let campaigns = AdsApp.campaigns()
.withCondition("Name='My Campaign'")
.get();
唯一性
廣告活動 ID 和廣告群組 ID 都是專屬的,不會有兩個廣告活動或廣告群組共用同一個 ID。不過,廣告和關鍵字有複合 ID:關鍵字的專屬 ID 是由廣告群組 ID 和關鍵字 ID 組合而成。同樣地,廣告的專屬 ID 是廣告群組 ID 和廣告 ID 的組合。這會影響 selector.withIds()
的呼叫方式。
如果是廣告活動和廣告群組,selector.withIds()
預期會收到數字陣列:
let ids = [123123, 234234, 345345];
let campaignSelector = AdsApp.campaigns().withIds(ids);
不過,如果是廣告和關鍵字,selector.withIds()
需要的是雙元素陣列的陣列,第一個元素是廣告群組 ID。以下程式碼片段會從廣告群組中擷取三個關鍵字:
let adGroupId = 123123;
let keywordSelector = AdsApp.keywords().withIds([
[adGroupId, 234234],
[adGroupId, 345345],
[adGroupId, 456456]
]);
擷取廣告時也適用相同的建構函式。
臨時編號
使用含有多項作業的變動要求時,您偶爾需要使用暫時 ID 將資源彼此連結,因為您必須等到 API 回應傳回後,才能取得完整資源名稱。臨時 ID 必須是從 -1 開始的負數,且不得在同一個變動要求中重複。如要有效使用臨時 ID,您必須編寫一些程式碼,確保不會建立重複的臨時 ID:
let nextId = -1;
function getNextTempId() {
const ret = nextId;
nextId -= 1;
return ret;
}
每次後續呼叫 getNextTempId
時,傳回的數字都會比前一次少 1。由於所有暫時 ID 都必須是負數,因此請從 -1 開始。
臨時 ID 不會跨工作或變更要求保留。如要參照先前變更要求中建立的資源,請使用實際的資源名稱。
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-09-10 (世界標準時間)。
[null,null,["上次更新時間:2025-09-10 (世界標準時間)。"],[[["\u003cp\u003eMost Google Ads entities have a \u003ccode\u003egetId()\u003c/code\u003e method, which returns a unique identifier that can be useful for linking data, improving performance, and referencing external databases.\u003c/p\u003e\n"],["\u003cp\u003eWhen working with reports, IDs can connect report rows to specific Google Ads entities.\u003c/p\u003e\n"],["\u003cp\u003eFetching entities by ID is often faster than using other methods like filtering by name.\u003c/p\u003e\n"],["\u003cp\u003eCampaign and ad group IDs are unique, while ad and keyword IDs are composite, requiring both the ad group ID and their individual ID for unique identification.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eselector.withIds()\u003c/code\u003e method is used to fetch entities by ID, taking an array of numbers for campaigns and ad groups and an array of two-element arrays (ad group ID and entity ID) for ads and keywords.\u003c/p\u003e\n"]]],[],null,["Most Google Ads entities expose a `getId()` method that returns their\nidentifier. While not strictly necessary in most cases, IDs may come in handy\nwhen\n\nWorking with [reports](/google-ads/scripts/docs/features/reports)\n: IDs provide a good way to link a report row to the actual Google Ads entity.\n\nMaintaining a mapping with an external datastore\n: You may already have ID-based information stored in your own database.\n\nLooking for a bit of a performance boost\n\n: Fetching by IDs is often quicker than alternatives. The code for fetching a\n single entity is a bit easier too:\n\n let campaigns = AdsApp.campaigns()\n .withIds([678678])\n .get();\n // versus\n let campaigns = AdsApp.campaigns()\n .withCondition(\"Name='My Campaign'\")\n .get();\n\nUniqueness\n\nCampaign IDs and ad group IDs are unique: no two campaigns or ad groups will\never share the same ID. Ads and keywords, however, have composite IDs: a unique\nidentifier of a keyword is a combination of its ad group ID and keyword ID.\nLikewise, a unique identifier of an ad is a combination of its ad group ID and\nad ID. This has implications for the way `selector.withIds()` is called.\n\nFor campaigns and ad groups, `selector.withIds()` expects an array of numbers: \n\n let ids = [123123, 234234, 345345];\n let campaignSelector = AdsApp.campaigns().withIds(ids);\n\nFor ads and keywords, however, `selector.withIds()` needs an array of\ntwo-element arrays, the first element being the ad group ID. The following\nsnippet retrieves three keywords from an ad group: \n\n let adGroupId = 123123;\n let keywordSelector = AdsApp.keywords().withIds([\n [adGroupId, 234234],\n [adGroupId, 345345],\n [adGroupId, 456456]\n ]);\n\nThe same construct applies when fetching ads.\n\nTemporary IDs\n\nWhen working with a [mutate request](/google-ads/scripts/docs/features/mutate)\nwith multiple operations, you'll occasionally need to use\n[temporary IDs](/google-ads/api/docs/batch-processing/temporary-ids) to link\nresources to each other, since the full resource names won't be available until\nyou get the API response. Temporary IDs must be negative numbers starting with\n-1, and cannot repeat within the same mutate request. In order to use temporary\nIDs effectively, you'll have to write some code to ensure that you don't create\nduplicate temporary IDs: \n\n let nextId = -1;\n\n function getNextTempId() {\n const ret = nextId;\n nextId -= 1;\n return ret;\n }\n\nEach successive call to `getNextTempId` will return a number one less than the\nprevious. Since all temp IDs must be negative, start at -1.\n\nTemporary IDs are not remembered across jobs or mutate requests. To reference a\nresource created in a previous mutate request, use its actual resource name."]]