開始使用

本文件詳細說明使用 Google Site Verification API 所需的背景知識。

引言

Google Site Verification API 適用於想要撰寫應用程式或服務,以自動驗證網站或網域擁有權的程序。由於只有部分 Google 服務只能由網站或網域擁有者使用,因此請務必提供這項資訊。您可以使用 Google Site Verification API 驗證已驗證的使用者是網域或網站的擁有者,這可能是透過程式佈建其他 Google 服務的第一個步驟。

這份文件假設您熟悉網路程式設計概念、網路資料格式,也能夠透過程式修改網站或網域的檔案或 DNS 記錄。

總覽

您可以使用 Google Site Verification API 修改使用者的 Google 網站驗證資料,使用者如果驗證資料顯示他們是特定網站網域的擁有者,使用者就只能存取特定 Google 服務。您可以使用這個 API 為經過驗證的使用者產生驗證權杖,您的程式碼能以多種方式在自家網站或網域記錄中放置。權杖設定完成後,您就可以呼叫 API,要求 Google 檢查權杖。如果 Google 找到權杖,就會將已驗證的使用者註冊為網站或網域的擁有者。您也可以使用這個 API 替使用者修改擁有權清單,或是完全移除網站擁有權。

所有 API 呼叫都必須由已驗證的使用者進行授權,所有 API 呼叫則會在通過驗證的使用者帳戶中執行。

以這個 API 為例,假設您提供網站代管服務,您的使用者想使用 Google 的 Search Console 取得自家網站的相關資訊。為達成此目標,Google 必須知道他們確實擁有該應用程式。因此,您可以為使用者提供介面,要求他們驗證網站的擁有權。開發人員可以授權讓應用程式存取驗證資料,並執行程式碼來代表自己要求權杖、將其放在網站結構的檔案中,並要求 Google 進行檢查。Google 找到權杖後,會以更新驗證資料的方式,向使用者授予網站擁有權。現在可以使用 Search Console 取得所需資訊。

事前準備

建立 Google 帳戶

請確認您已設定 Google 帳戶。建議您使用獨立的 Google 帳戶進行開發及測試,避免發生意外資料遺失的情況。

熟悉網站驗證

如果您還不熟悉 Google Site Verification API 的概念,建議您先閱讀本文件、嘗試驗證使用者介面,並詳閱相關說明文件,再開始撰寫程式碼。

瞭解如何授權要求

您的應用程式傳送至 Google Site Verification API 的所有要求都必須包含授權權杖。這個憑證也可讓 Google 識別您的應用程式。

關於授權通訊協定

您的應用程式必須使用 OAuth 2.0 對要求進行授權,系統不支援其他授權通訊協定。如果您的應用程式使用使用 Google 帳戶登入功能,系統會為您處理部分授權事項。

使用 OAuth 2.0 對要求進行授權

所有向 Google Site Verification API 發出的要求都必須由通過驗證的使用者進行授權。

OAuth 2.0 授權程序 (或「流程」) 的細節會根據您編寫的應用程式類型而有所不同。下列一般程序適用於所有應用程式類型:

  1. 建立應用程式後,請透過 Google API 控制台註冊應用程式。接著 Google 會向您提供稍後需要的資訊,例如用戶端 ID 和用戶端密碼。
  2. 在 Google API 控制台中啟用 Google Site Verification API。(如果 API 控制台裡沒有列出該 API,則可略過這個步驟)。
  3. 當應用程式需要存取使用者資料時,會向 Google 要求特定的存取範圍
  4. Google 會向使用者顯示同意畫面,請對方授權您的應用程式要求部分資料。
  5. 如果使用者同意,Google 即會授予短期存取憑證給您的應用程式。
  6. 您的應用程式向使用者要求資料,並且在要求中附上存取憑證。
  7. 如果 Google 判定您的要求與憑證有效,便會傳回您要求的資料。

部分流程包含額外步驟,例如使用「更新憑證」來取得新的存取憑證。如要進一步瞭解各類應用程式的流程,請參閱 Google 的 OAuth 2.0 說明文件

以下是 Google Site Verification API 的 OAuth 2.0 範圍資訊:

範圍 意義
https://www.googleapis.com/auth/siteverification 具備現有已驗證網站的完整讀取權限,以及驗證新網站的權限。
https://www.googleapis.com/auth/siteverification.verify_only 能夠驗證新網站,以及現有已驗證網站的讀取權限。

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

提示:Google API 用戶端程式庫可以為您處理部分授權程序,且適用於多種程式設計語言;詳情請參閱程式庫和範例頁面

Google Site Verification API 背景

概念

您可以使用 Google Site Verification API 建立使用者對下列網路資源的擁有權:

  • 網域:網域或子網域。系統會將網域擁有者視為該網域下所有網站和子網域的擁有者。例如,bar.com 的直接擁有者也視為 foo.bar.com 的間接擁有者。
  • 網站:與網站基本網域和路徑對應的網址。因此,系統會將網站的擁有者視為其下所有網站的擁有者。比方說,系統會將「http://www.example.com/site」的擁有者視為「http://www.example.com/site/subsite」的擁有者。

由於網域擁有權比網站擁有權更廣泛,建議您盡可能驗證網域,

建立擁有權的程序是從代表使用者要求「驗證權杖」的流程開始。驗證權杖是一種特殊字串,您的程式碼必須將其置於自家網站或網域上。完成憑證後,應用程式即可向 Google Site Verification API 發出要求,藉此檢查權杖,並在找到憑證時記錄擁有權。

限制

基於安全性和技術理由,Google Site Verification API 會強制執行某些使用限制:

  • 僅限已驗證使用者的資料存取權:所有作業都需要使用者驗證和授權
  • 僅針對已驗證的使用者完成驗證:API 只能驗證目前已驗證帳戶的網站或網域的擁有權。不過,通過驗證的使用者可以在網站擁有權通過驗證後,將擁有權委派給其他使用者。請注意,每當變更擁有權清單,所有擁有者都會收到電子郵件通知。
  • 僅限標準化網址和網域名稱。Google Site Verification API 不支援 IDN (國際網域名稱) 編碼。如有必要,請務必使用 Punycode 將所有網址、網域名稱和電子郵件地址網域正規化為標準網域名稱字元集 (RFC 1034 §3.5)。

驗證方法和權杖

API 針對驗證的獨立階段提供呼叫:

  • 放置驗證權杖:發出 API 呼叫,藉此擷取驗證權杖並放在已驗證使用者的網站上。如果使用者有多個網站,您必須為每個網站取得不同的權杖。
  • 檢查驗證權杖是否存在:系統會透過獨立 API 呼叫,要求 Google 檢查權杖,以驗證已驗證使用者擁有的網站。

有許多方法可以驗證你的應用程式可以使用的網站或網域,你可採用最符合自身需求的方法。放置權杖的位置和權杖類型取決於您選用的驗證方法。

網域驗證方法

網域有兩種驗證方法:

DNS_CNAME

您的應用程式會使用擁有者的權杖 (可能透過網域註冊商使用記錄資料) 來建立新的 CNAME 記錄。這個權杖由兩個部分組成,並以空格分隔,第一個部分是新的 CNAME 記錄名稱,第二個部分則是新的 CNAME 記錄值。

DNS_TXT

您的應用程式會使用擁有者的網域記錄等資料,為擁有者的網域建立新的 TXT 記錄。

詳情請參閱 DNS 驗證方法的說明中心文章。

網站驗證方法

以下提供三種驗證方法:

檔案
您的應用程式會將憑證以檔案的形式顯示在擁有者的網站上。您必須建立名稱為權杖權杖的字串,並在其中加入下列內容:
google-site-verification: token

舉例來說,如果使用者擁有 http://www.example.com/ 網站,而且傳回的權杖是 google12cfc68677988bb4.html,那麼只要前往 http://www.example.com/google12cfc68677988bb4.html (在其網站頂層) 建立檔案,並在當中加入內容即可:

google-site-verification: google12cfc8677988bb4.html

詳情請參閱檔案驗證方法的說明中心文章。

Meta 鍵

您的應用程式會以 HTML <meta> 標記的形式將權杖插入擁有者檔案頂層中,位於預設檔案 (index.html、default.html 等) 的 <head> 元素中。包含中繼驗證權杖的 HTML 檔案可能如下所示:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

詳情請參閱中繼驗證方法說明中心的說明文件。

數據分析

您的應用程式使用了現有的 Google Analytics (分析) 追蹤程式碼,而這組程式碼已存在於擁有者的網站上。追蹤程式碼必須位於 Analytics (分析) 帳戶中,且程式碼片段必須置於 HEAD 標記中才能運作。詳情請參閱 Analytics (分析) 驗證方法的說明中心文章。

代碼管理工具

您的應用程式使用已存在在擁有者網站上現有的 Google 代碼管理工具容器程式碼。容器程式碼必須屬於其代碼管理工具帳戶。如需更多資訊,請參閱說明中心代碼管理工具驗證方法的說明文件。

建議您先透過網站驗證使用者介面手動驗證幾個網站,藉此瞭解核心概念和工作流程。

資料模型

網站資源

Google Site Verification API 會將 REST 語意 (HTTP GETPOST 等) 套用至名為網路資源的實體,網站資源是指屬於已驗證使用者的網站或網域。

以下是網站資源範例:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

id 欄位是這項網站資源的專屬 ID。方便您用來擷取和擷取這個特定網站資源。儲存 list 作業輸出內容的 id 欄位,以供日後使用。

site 物件包含網路資源的網址或網域名稱,以及資源類型。網站是以 SITE 類型指定;網域類型為 INET_DOMAIN

owners 陣列是網站資源的完整擁有者清單,以電子郵件地址表示。已驗證擁有者的擁有者可以新增或移除擁有者清單的電子郵件地址,將其他使用者的擁有權授予或撤銷其他使用者的擁有權。如果擁有者在網站或網域上擁有自己的權杖,那麼擁有者和任何共同擁有者也會出現在擁有者清單中。

獲得共同擁有權的使用者也可以將共同擁有權授予,前提是網站上至少有一位已驗證擁有者。

網路資源集合

網站資源集合是屬於已驗證使用者的所有網路資源完整清單。只要在已驗證的使用者的網站資源清單中加入新的網站資源,即可驗證網站或網域的擁有權。只有通過驗證的網站或網域成功加入集合。

如「限制」一節所述,您無法透過 Site Verification API 存取屬於已驗證使用者以外的網路資源。