使用入门

本文档详细介绍了使用 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（国际域名）编码。如有必要，请务必使用 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

您的应用会以 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 跟踪代码。跟踪代码必须属于客户的 Google Analytics 账号，且代码段必须位于 HEAD 标记中才能正常工作。如需了解详情，请参阅有关 Google 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 字段是该网站资源的唯一标识符。您可以使用它来引用此特定网络资源，以进行检索和修改。存储 list 操作输出中的 id 字段，以便稍后用作标识符。

site 对象包含 Web 资源的网址或域名，以及资源类型。网站以 SITE 类型指定；域以 INET_DOMAIN 类型指定。

owners 数组是网站资源所有者的完整列表，用其电子邮件地址表示。通过在所有者列表中添加或删除电子邮件地址，经过身份验证的用户可以授予其他用户共同所有权或撤消所有权。在网站或网域上放置了自己的令牌的其他所有者也会与其所有共同所有者一起显示在所有者列表中。

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

网络资源集合

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

如限制部分中所述，您无法通过 Site Verification API 访问属于未经身份验证的用户以外的用户的网络资源。