入門

本文件適用於想要透過 AdSense Host API 取得 AdSense 帳戶相關資訊的開發人員。我們假設本文的讀者對網頁程式設計概念和網頁資料格式都非常熟悉。

內容

事前準備

取得 AdSense 帳戶

您需要有測試用的 AdSense 帳戶。如果已有測試帳戶,就可以前往 AdSense 使用者介面設定、修改或查看測試資料。

熟悉 AdSense

如果您還不熟悉 AdSense 相關概念,請先參閱 AdSense 簡介資訊並測試使用者介面,再開始撰寫程式碼。

註冊應用程式

如果要使用 AdSense Host API,您必須向 Google 註冊要開發的應用程式:

  1. 前往 API 主控台
  2. 登入 Google 帳戶或建立一個。
  3. 新建專案。
  4. 在新建的專案中,按一下 AdSense Host API 底下的 [請求存取] 連結。

如果是 OAuth 2.0 應用程式,請按照使用 OAuth 2.0 存取 Google API 中所述的其他步驟進行。

注意事項:用於註冊的 Google 帳戶應該是您的開發人員帳戶,也就是說,您希望應用程式使用者看到的應用程式開發人員帳戶。這個帳戶不需要與 AdSense 登入資訊連結,因為使用者會在使用應用程式時獲得本身帳戶的存取權。

瞭解 AdSense Host API

基本概念

AdSense Host API 是以某些 AdSense 基本概念為基礎:

  • 廣告用戶端:廣告用戶端代表 AdSense 帳戶與 AdSense 產品之間的關聯,例如多媒體廣告或搜尋廣告。AdSense 帳戶可以有一或多個廣告用戶端。
  • 管道:管道可用來追蹤某個網頁或網域的成效。
  • 報表:報表可讓您查看收益資料,以及這些收益的影響因素。使用管道,您就能針對整個帳戶或一小部分的廣告空間執行報表。

支援的操作

API 目前支援的操作如下表所示。

操作 說明 REST HTTP 對應
列出 列出集合中所有資源。 組合 URI 上的 GET
取得 取得某項資源。 資源 URI 上的 GET
產生 根據某項資源產生結果集。僅限用於報表。 收集 URI 上的 GET/POST;此時,您會將資源視為用於產生報表的定義來傳入。

所有操作都需要經過驗證

呼叫樣式

REST 是一種特定類型的軟體架構,目的在於提供一種方便且一致的資料請求及修改方法。

REST 是「表徵狀態轉移」(Representational State Transfer) 的簡稱。就 Google API 的情況而言,它指的是使用 HTTP 動詞來擷取並修改 Google 儲存的資料表示法。

在採用 REST 架構的系統中,資源會儲存在資料儲存區中;在用戶端送出要求伺服器執行特定動作 (例如建立、擷取、更新或刪除資源) 的請求之後,伺服器便會執行該動作並送出回應,而此回應大多採用指定資源表示法的形式。

在 Google 採用 REST 的 API 中,用戶端會使用 POSTGETPUTDELETE 等 HTTP 動詞來指定動作,它會使用一個全球唯一的 URI 來指定資源,其格式如下:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

因為所有 API 資源都具有專屬的 HTTP 可存取 URI,因此 REST 不但支援資料快取,還能與網路的分佈式基礎架構完美地搭配運作。

如果要進一步瞭解 REST,建議您參考以下第三方文件:


AdSense Host API 中的 REST

受支援的操作直接對應於 REST HTTP 動詞,如 AdSense Host API 作業中所述。

AdSense Host API URI 專用格式如下:

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

其中 resourceID 是廣告用戶端、網址管道、自訂管道或報表集合的識別碼,而 parameters 是任何要套用至查詢的參數。

resourceID 路徑延伸的格式可讓您找出目前對哪個資源執行操作,例如:

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

關於 API 中一共有哪些 URI 用於各項支援的操作,都已總結在 AdSense Host API 參考資料文件中。

以下舉例說明此格式在 AdSense Host API 中的運作方式。

列出廣告用戶端:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

資料格式

JSON (JavaScript Object Notation) 是一種不涉及語言的常用資料格式,可透過簡單的文字來呈現多變的資料結構。詳情請參閱 json.org

提出請求

授權請求

凡是您應用程式向 AdSense Host API 發出的請求,都必須包含一個授權權杖,這個權杖也會識別您的 Google 應用程式。

關於授權通訊協定

您的應用程式必須使用 OAuth 2.0 授權請求。不支援其他授權通訊協定。

使用 OAuth 2.0 授權請求

凡是向 AdSense Host API 發出的請求,都必須由通過驗證的使用者進行授權。

OAuth 2.0 授權流程 (以下稱「流程」) 的細節會因您撰寫的應用程式類型而異。以下一般程序適用於所有應用程式類型:

  1. 當您建立應用程式時,必須透過 Google 開發人員主控台註冊。接著,Google 將會提供您隨後需要用到的資訊,例如用戶端編號和客戶密碼。
  2. 在 Google 開發人員主控台中,啟動 AdSense Host API (如果開發人員主控台中並未顯示這個 API,請跳過這個步驟)。
  3. 當您的應用程式需要存取使用者資料時,會向 Google 要求某個範圍的存取權。
  4. Google 會向使用者顯示同意畫面,要求他們授權您的應用程式索取部分資料。
  5. 取得使用者同意後,Google 會提供該應用程式一個短期的存取權杖
  6. 您的應用程式會請求使用者資料,並將存取權杖加進請求。
  7. 如果 Google 判定您的請求和權杖是有效的,便會傳回您請求的資料。

部分流程包含額外的步驟,例如使用重新整理權杖來取得新的存取權杖。如果要進一步瞭解各類應用程式的流程,請參閱 Google 的 OAuth 2.0 說明文件

OAuth 2.0 的 AdSense Host API 範圍資訊如下:

範圍 意義
https://www.googleapis.com/auth/adsensehost AdSense 資料的讀取/寫入存取權。

如要透過 OAuth 2.0 請求存取權,您的應用程式需要範圍資訊,以及 Google 在您註冊應用程式時提供的資訊 (例如用戶端編號和用戶端密鑰等)。

訣竅:Google API 用戶端程式庫可以為您處理部分授權流程,且適用於各式各樣的程式設計語言;詳情請參閱程式庫和範例網頁

詳情請參閱 OAuth 2.0 一節。

提出請求

最後一個步驟是提出 API 請求。如果您尚未使用任何用戶端程式庫,可以參閱參考文件

如果您正在使用用戶端程式庫,這項工作就會簡單許多。參閱範例和程式庫這份完整的指南,您就能瞭解如何使用 Java、Python、PHP 或 JavaScript 用戶端程式庫提出第一個請求。

OAuth 2.0

AdSense Host API 的驗證和授權是由 OAuth 2.0 來處理。不過,由於 AdSense Host 使用模式有幾種特性,因此處理方式可能與其他 Google API 略有不同。

參與者

OAuth 2.0 請求會牽涉到三個實體:

  • 使用者:授與個人資料的存取權
  • 開發人員:透過該應用程式來請求使用者資料的存取權
  • Google:驗證各方並提供 API 服務

不過,就 AdSense Host API 而言,使用者與開發人員其實是同一人,因為身為開發人員的使用者會使用 API 來取得本身 AdSense 帳戶的存取權,並透過該帳戶存取發佈商的帳戶。

建立專案

您可以在 API 主控台網頁中新建專案。
圖 1:在 API 主控台上的新專案

首先,您必須在 API 主控台上建立新專案,方法與您所使用的其他 Google API 一樣。您需要先將用來建立開發人員專案的 Google 帳戶加入許可清單,才能存取 AdSense Host API;請務必使用申請時我們為您建立的沙箱帳戶,或是使用您實際的 AdSense 帳戶 (如果您的 API 已完成安裝並上線)。

[服務] 分頁可讓您選擇專案所用的 API。
圖 2:已為專案啟用及停用的 API

如要進一步瞭解如何建立 Google API 專案,請參閱 API 主控台說明文件

設定 API 存取權

建立專案後,您必須建立 OAuth 2.0 用戶端編號來啟用專案的 API 存取權。

您可在 [API 存取權] 分頁中建立 OAuth 2.0 用戶端。
圖 3:在 API 主控台中新建 OAuth 2.0 用戶端

您有多種做法可以選擇,但最好建立「已安裝的應用程式」這個專案來簡化後續步驟。

一次驗證,永久儲存

現在,您必須用自己的 AdSense 帳戶進行驗證,這可以透過一小段指令碼或測試應用程式來完成 (您可參考程式碼範例)。

驗證後,請務必將您在授權步驟中取回的更新權杖儲存起來。這是沒有期限的長效權杖,除非您已明確撤銷存取權;由於您就是使用者,所以應該不會撤銷對自有應用程式的存取權!

請將更新權杖儲存在應用程式的資料儲存區中,以供未來所有驗證請求使用。

使用應用程式中儲存的權杖

取得更新權杖之後,無論權杖是透過「網路伺服器應用程式」流程或「已安裝的應用程式」流程產生,都不會造成任何影響。必要時,您可以直接使用這個權杖建立新存取權杖的權杖更新請求。如果您使用的是其中一個用戶端程式庫,請查看文件說明來瞭解如何指定您自己的權杖;您可能必須修改自動產生的檔案或資料庫項目。

總結

完成上述步驟後,OAuth 2.0 流程只會執行一次,而所有請求之後都會在背景進行,不論是您網站的一般使用者 (發佈商) 還是身為開發人員的您,都不需要手動進行任何操作。

公告

透過 AdSense API 公告隨時掌握新版本、新功能和重要服務更新。

傳送您對下列選項的寶貴意見...

這個網頁
AdSense Host API
AdSense Host API