使用入门

本文档将详细介绍使用 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 调用都是在经过身份验证的用户帐号的上下文中执行。

举个具体的例子,假设您提供了这项网站服务的托管服务。 您的用户希望能够使用 Google 的 Search Console 获取其网站的相关信息。为了让 Google 能够做到这一点,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(国际域名)编码。如有必要,请务必使用 Punycoding 将所有网址、域名和电子邮件地址域名标准化为标准域名字符集 (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

您的应用会在所有者网站的顶层、默认文件(index.html、default.html 等)的 <head> 元素中以 HTML <meta> 标记的形式插入令牌。带有 Meta 验证令牌的 HTML 文件可能如下所示:

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

如需了解详情,请参阅有关元验证方法的帮助中心文档。

分析

您的应用使用所有者网站上已有的现有 Google Analytics(分析)跟踪代码。跟踪代码必须属于他们的 Google Analytics(分析)帐号,并且代码段必须位于 HEAD 标记中才能正常工作。如需了解详情,请参阅有关 Google Analytics(分析)验证方法的帮助中心文档。

跟踪代码管理器

您的应用使用了所有者网站上已有的 Google 跟踪代码管理器容器代码。容器代码必须属于其跟踪代码管理器帐号。如需了解详情,请参阅有关跟踪代码管理器验证方法的帮助中心文档。

如果您先尝试通过网站验证界面手动验证一些网站,这对理解核心概念和工作流程很有帮助。

数据模型

网络资源

Google Site Verification API 将 REST 语义(HTTP GETPOST 等)应用于名为网络资源的实体。网络资源是属于经过身份验证的用户的网站或网域。

以下是 Web 资源的示例:

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

id 字段是此 Web 资源的唯一标识符。您可以使用它引用此特定网络资源以进行检索和修改。存储 list 操作输出的 id 字段,以便稍后用作标识符。

site 对象包含网络资源的网址或域名以及资源类型。网站使用 SITE 类型指定;网域使用 INET_DOMAIN 类型指定。

owners 数组是 Web 资源的所有者的完整列表,由其电子邮件地址表示。通过在所有者列表中添加或移除电子邮件地址,经过身份验证的用户可以授予共同所有权或撤消其他用户的所有权。已在网站或网域上自行添加令牌的其他所有者及其任何共同所有者也会显示在所有者列表中。

已被授予共同所有权的用户也可以授予共同所有权,但前提是网站上至少有一位经过验证的所有者拥有令牌。

网络资源收集

网络资源集合是属于经过身份验证的用户的所有网络资源的完整列表。只需尝试向已通过身份验证的用户的网络资源添加新网络资源,即可验证网站或网域的所有权。只有经过验证的网站或网域才能成功添加到集合中。

如前文的限制部分所述,归已验证用户以外的用户的网络资源无法通过 Site Verification API 访问。