直接提出請求

建議您在導入時使用用戶端程式庫和範例。不過,要是您與 API 的整合包含特定需求 (例如使用不支援的語言),您可以按照下方說明提出直接請求。

內容

呼叫樣式

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 Management API 中的 REST

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

AdSense Management API URI 專用格式如下:

https://www.googleapis.com/adsense/v1.4/resourceID?parameters

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

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

https://www.googleapis.com/adsense/v1.4/adclients
https://www.googleapis.com/adsense/v1.4/adclients/adClientId
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits/adUnitId
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/urlchannels
...

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

以下舉幾個例子來說明此格式在 AdSense Management API 中的運作方式。

列出廣告用戶端:

GET https://www.googleapis.com/adsense/v1.4/adclients/

列出廣告用戶端 ca-pub-1234567890123456 的廣告單元:

GET https://www.googleapis.com/adsense/v1.4/adClients/ca-pub-1234567890123456/adunits

資料格式

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

授權請求

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

關於授權通訊協定

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

使用 OAuth 2.0 授權請求

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

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

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

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

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

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

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

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

提出請求

最後一個步驟是提出 API 請求。如需詳細資訊,請參閱參考文件