廣告連結庫是公用透明度工具，可讓您檢視 Bing.com 上顯示的所有廣告。 您可以依廣告副本中出現的廣告名稱和關鍵詞來搜尋廣告，而且您會看到廣告內容和其他廣告詳細數據。 廣告連結庫是合規性工作的一部分，以確保我們為使用者建立安全且開放的因特網。
廣告連結庫 API 資源
基底 URI
以下是您將樣本附加至的基底 URI：
https://adlibrary.api.bingads.microsoft.com/api/v1/
範本
若要建立用來查詢 Ad Library 的端點，請將適當的範本附加至基底 URL：
| 範本 | HTTP 動詞 | 描述 | 資源 |
|---|---|---|---|
| 廣告 | Get | 依名稱取得廣告商 參數： - 前 (int32，預設值 3) - 略過 (int32，預設值為0) - searchText (字串，預設 “”) |
數位廣告<商> |
| ({TenantId}) 或 廣告商/{廣告商標識符} |
Get | 依標識碼取得廣告商 參數：無 注意：應變數標識碼可以是 AccountId 或 VerifiedAdvertiserId。 多個帳戶可能會在相同的身分識別下進行驗證。 如果要求已驗證的 AccountId，則會改為傳回父代 VerifiedAdvertiserId。 |
廣告 |
| 廣告 | Get | 依廣告商/內容取得廣告 參數： • 前 (int32，預設值 12) • 略過 (int64，預設 0) • startDate (字串) • endDate (字串) • 格式為 'yyyy-MM-dd' 的日期 • countryCodes (字串) 逗號分隔值，也就是 '10,26,53' • (int64) • searchText (字串) |
數位廣告<> |
| 廣告 ({AdId}) 或 Ads/{AdId} |
Get | 依標識碼取得廣告 參數：無 |
廣告 |
數據物件
以下是 API 所使用的要求和回應物件：
| 物件 | 描述 |
|---|---|
| 廣告 | 定義廣告商。 |
| 廣告 | 定義廣告。 |
| AdDetails | 定義有關廣告的其他詳細數據。 |
| CountryImpressionShare | 定義國家/地區的廣告曝光率共用。 |
| TargetTypeDetails | 定義廣告所使用之目標類型的詳細數據。 |
廣告
定義廣告商。
| 名稱 | 值 | 類型 |
|---|---|---|
| TenantId | 識別廣告商的標識碼。 注意：如果廣告商已驗證，這可能是 AccountId 或 VerifiedAdvertiserId。 VerifiedAdvertiserIds 可能會涵蓋多個帳戶，如果 是在相同的廣告商下驗證，且已驗證的 AccountId 要求會改為傳回父代 VerifiedAdvertiserId。 |
Long |
| 廣告商名稱 | 已驗證之廣告商的帳戶名稱或法律名稱。 | String |
| 傳回者帳戶 | 註冊廣告商的國家/地區。 | String |
| IsVerified | 布爾值，表示是否驗證廣告商。 | 布林值 |
廣告
定義廣告。
| 名稱 | 值 | 類型 |
|---|---|---|
| AdId | 識別廣告的標識碼。 | Long |
| 廣告商名稱 | 已驗證之廣告商的帳戶名稱或法律名稱。 | String |
| TenantId | 識別廣告商的標識碼。 | Long |
| 標題 | 廣告復本的標題部分。 注意：對於動態廣告類型，可能會有多個變化，而標題、描述、URL 和資產可能只是廣告上次提供時的最近代表性版本。 |
String |
| 說明 | 廣告復本的描述部分。 | String |
| DisplayUrl | 廣告所顯示的 URL，或特定廣告類型的商家名稱。 | String |
| DestinationUrl | 廣告鏈接的實際URL。 | String |
| AssetJson | 資產資源的 JSON URL | String |
| AdDetails | 物件，包含有關廣告的其他詳細數據。 | AdDetails |
AdDetails
定義廣告的其他詳細數據。
| 名稱 | 值 | 類型 |
|---|---|---|
| PaidForByName | 如果與帳戶擁有者不同，則為廣告付費的客戶名稱。 | String |
| StartDate | 廣告第一次執行的UTC日期，或廣告連結庫記錄第一個合格曝光的日期。 注意：自 2023 年 6 月起，廣告連結庫只會記錄歐盟 (歐盟) 或歐洲 (EEA) 的廣告曝光。 廣告的實際開始日期可能會早於我們的廣告連結庫的啟動日期，或廣告收到其第一個合格曝光的日期。 |
String |
| EndDate | 廣告上次執行的 UTC 日期，或廣告連結庫記錄最後合格曝光的日期。 注意：除了上述注意事項之外，廣告庫中出現的資訊可能會延遲 1-3 天，因此如果廣告仍在使用中，EndDate 可能不會反映過去幾天顯示的較新印象。 |
String |
| TotalImpressionsRange | 範圍，代表廣告在 EU 和 EEA 中收到的曝光總數。 | String |
| ImpressionsByCountry | 索引鍵/值組的清單，代表每個歐盟或 EEA 成員國家/地區的曝光率百分比。 | array<CountryImpressionShareObject> |
| TargetTypes | 用於廣告目標的目標類型清單，以及是否也用於排除。 注意：這是在廣告執行期間用於所有合格曝光之所有目標類型的匯總清單，不一定表示哪些因素用於特定曝光。 |
array<TargetTypeDetails> |
| RestrictionReason | 如果存在，則為廣告被限制無法進一步提供或顯示在廣告媒體櫃中的原因。 | RestrictionReason |
CountryImpressionShare
定義指定國家/地區的廣告曝光分享。
| 名稱 | 值 | 類型 |
|---|---|---|
| 國家/地區 | 顯示廣告的國家/地區。 | 國家/地區 |
| ImpressionShare | 國家/地區廣告曝光數的共用，以百分比表示 (也就是 17.3%) 。 | String |
TargetDetails
定義指定國家/地區的廣告曝光分享。
| 名稱 | 值 | 類型 |
|---|---|---|
| TargetType | 用於目標的參數。 | TargetType |
| UsedForExclusion | 表示目標類型是否也用於排除。 | 布林值 |
數值集
以下是 API 所使用的值集。
| 物件 | 描述 |
|---|---|
| 國家/地區 | 定義廣告連結庫針對篩選和報告廣告曝光數所考慮的國家/地區值。 |
| TargetType | 定義 Ad Library 追蹤的目標參數類型。 |
| RestrictionReason | 定義廣告被限制無法進一步提供或顯示在廣告媒體櫃中的原因。 |
國家/地區
定義廣告連結庫針對篩選和報告廣告曝光數所考慮的歐盟國家/地區和歐洲經濟區域成員的值。
| 名稱 | 值 |
|---|---|
| 奧地利 | 10 |
| 比利時 | 14 |
| 保加利亞 | 26 |
| 克羅埃西亞 | 49 |
| 賽普勒斯 | 207 |
| 捷克文 | 51 |
| 丹麥 | 53 |
| 愛沙尼亞 | 61 |
| 芬蘭 | 65 |
| 法國 | 66 |
| 德國 | 72 |
| 希臘 | 76 |
| 匈牙利 | 88 |
| 愛爾蘭 | 92 |
| 義大利 | 93 |
| 拉脫維亞 | 104 |
| 立陶宛 | 108 |
| 盧森堡 | 109 |
| 馬爾他 | 115 |
| 荷蘭 | 129 |
| 波蘭 | 151 |
| 葡萄牙 | 152 |
| 羅馬尼亞 | 226 |
| 斯洛伐克 | 165 |
| 斯洛維尼亞 | 167 |
| 西班牙 | 170 |
| 瑞典 | 175 |
| 冰島 | 89 |
| 列支敦斯登 | 107 |
| 挪威 | 139 |
TargetType
定義 Ad Library 追蹤的目標參數類型。
| 名稱 | 值 | 描述 |
|---|---|---|
| 性別 | 1 | 以性別為目標。 |
| 年齡 | 2 | 以年齡群組為目標。 |
| 位置 | 3 | 以用戶位於或搜尋的地理區域為目標。 |
| MicrosoftAudiences | 22 | 以 Microsoft 定義的物件為目標，包括市場內對象、類似的物件，以及LinkedIn配置檔目標。 |
| DesignerAudiences | 25 | 以廣告定義的物件為目標，包括自定義物件、客戶比對清單和重新營銷清單。 |
API 驗證
與 Ad Library UI 一樣，Ad Library API 也可公開使用，不需要任何用戶註冊或登入。 不過，若要保護平臺的安全性和穩定性，未經驗證的要求在呼叫 API 的頻率，以及每個呼叫可要求的實體數目上會面臨更嚴格的限制。
若要使用具有更高限制的 Ad Library API，您需要：
- Microsoft 帳戶
- Microsoft Advertising 帳戶
- 開發人員令牌
若要建立 Microsoft Advertising 帳戶，請移至 https://ads.microsoft.com。 如果您未登入您的 Microsoft 帳戶，系統會將您重新導向以登入您的帳戶或註冊帳戶。 登入之後，您可以選擇 註冊新的 Microsoft Advertising 帳戶。 選取註冊選項，然後選取 [ 繼續]。
驗證您的認證
廣告連結庫 API 使用與 Bing 廣告 API 相同的驗證配置。 如需使用 OAuth 驗證 Microsoft 帳戶認證的詳細資訊，請參閱使用 Microsoft 身分識別平台 進行驗證。
您可以使用適用於 .NET、Java 或 Python 的 Bing Ads SDK 來驗證 Microsoft 帳戶認證。 如需使用 SDK 取得存取令牌的詳細資訊，請參閱 C# | Java | Python。
注意：Bing 廣告 SDK 不提供 Ad Library API 的介面。 如果您也使用適用於 Microsoft Advertising 的 SDK 行銷活動，您應該只使用 SDK 來取得存取權杖。 否則，安裝 SDK 可能不值得額外負荷。
如果您未使用 Bing Ads SDK 進行驗證，請參閱在 C# 中驗證 Microsoft 帳戶認證，以取得示範如何使用 OAuth 驗證 Microsoft 帳戶認證的範例。
您的認證和開發人員令牌在何處使用？
若要增加限制，所有呼叫都必須指定：
- 設定為開發人員令牌的 DeveloperToken 標頭。
- 設定為存取令牌的 AuthenticationToken 標頭。
如需要求和回應可能包含之這些標頭的相關信息，請參閱 標頭。
最簡單的 Microsoft Advertising 帳戶 Sign-Up 步驟
如果您是想要存取廣告連結庫 API 的研究人員或監管者，但您還沒有 Microsoft Advertising 帳戶或想要在我們的平臺上公告，請完成下列步驟：
瀏覽 https://ads.microsoft.com/ 並選取 [立即註冊]。
使用現有的 Microsoft 帳戶登入，或選取 [ 建立一個！]
使用現有的電子郵件地址或電話號碼，或選 取 [取得新的電子郵件位址]。
如果您要建立新的電子郵件位址 (電子郵件地址、密碼、名字/姓氏、國家/地區和出生日期) ，請輸入上述資訊，並視需要解決 captcha。若要儘快跳過設定，請選取 [ 建立新活動] ，然後 選取 [切換至專家]。
選取 [略過營銷活動建立 ] 來設定沒有營銷活動的帳戶。
此時，已建立帳戶，而且不需要進一步的資訊。
