開始使用

本文件將詳細說明使用 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 (國際網域名稱) 編碼。請務必視需要使用標點符號，將所有網址、網域名稱和電子郵件地址網域正規化為標準網域名稱字元集 (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> 標記的形式插入預設檔案的 <head> 元素 (index.html、default.html 等)，包含 Meta 驗證權杖的 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 GET、POST 等) 套用至稱為網路資源的實體。「網路資源」是已驗證使用者的網站或網域。

以下是網路資源的範例：

{
  "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 欄位，以便稍後做為 ID。

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

owners 陣列是網路資源的擁有者完整清單，以電子郵件地址表示。只要在擁有者清單中新增或移除電子郵件地址，已通過驗證的使用者就能授予共同擁有權，或是撤銷其他使用者的擁有權。其他在網站或網域上放置自己權杖的擁有者，也會出現在擁有者清單以及他們的所有共同擁有者中。

此外，獲得共同擁有權的使用者也可以授予共同擁有權，但前提是至少有一位已驗證擁有者在網站上擁有權杖。

網路資源集合

網路資源集合會完整列出已驗證使用者的所有網路資源。您只須嘗試將新的網路資源加到已驗證使用者的網站資源集合中，即可驗證網站或網域的擁有權。只有已驗證的網站或網域才能順利加入集合。

如同「限制」一節所述，除了通過驗證的使用者之外，其他人無法透過 Site Verification API 存取屬於其其他使用者的網路資源。