调用 API

本文档介绍了如何使用 Google Site Verification API。

调用 API

请求格式

大多数受支持的网站验证操作会直接映射到 REST HTTP 动词（GET、POST、PUT、DELETE），如 Google Site Verification API 操作中所述。

Google Site Verification API URI 的具体格式为：

https://www.googleapis.com/siteVerification/v1/webResource/resourceID?parameters

其中 resourceID 是网站资源的标识符，parameters 是要应用于查询的任何参数。实际使用的参数因所执行的操作而异。此外，如果您使用的是 OAuth 2.0，则应在这些参数中设置 access_token。

列表查询不需要 resourceID，因此格式为：

https://www.googleapis.com/siteVerification/v1/webResource?parameters

您可以通过 getToken 操作专属的 URI 来调用该操作。getToken 调用的格式如下：

https://www.googleapis.com/siteVerification/v1/token?parameters

数据格式

Google Site Verification API 会返回 JSON 格式的数据。

JSON（JavaScript 对象表示法）是一种与语言无关的常见数据格式，可通过简单的文本来表示任意数据结构。如需了解详情，请参阅 json.org。

操作摘要

您可以对 Google Site Verification API 中的集合和资源调用六种不同的方法，如下表所述。API 网址相对于 https://www.googleapis.com/siteVerification/v1。

操作 说明 网址和语法
list

列出经过身份验证的用户的集合中的所有资源。

GET /webResource

请参阅 list 请求示例。
insert

验证网站或网域。如果成功，在用户集合中插入一个新的网络资源。

请求正文：请参阅网络资源。

查询参数：verificationMethod。用于此请求的验证方法。可能的值：FILE、META、ANALYTICS、TAG_MANAGER、DNS_TXT、DNS_CNAME

POST /webResource

请参阅insert 请求示例。
get

获取特定网络资源的最新数据。

GET /webResource/resourceID

请参阅 get 请求示例
update

修改特定资源的所有者列表。

请求正文：请参阅网络资源。

注意：

  • 您无法使用 update 从所有者列表中移除经过身份验证的用户。请改用 delete。
  • 您可以从所有者列表中移除任何在网站上没有验证令牌的用户。

PUT /webResource/resourceID

请参阅 update 请求示例。
delete

从用户的集合中移除资源（验证网站是否属于该用户）。

注意：

  • 在调用 delete 之前，您必须先从网站或网域中移除通过身份验证的用户的所有验证令牌。如果仍然存在任何令牌，系统会返回 HTTP 400（错误请求）错误。
  • 删除操作只会影响已通过身份验证的用户的所有权数据。所有其他用户（无论是委托用户还是独立验证的用户）在删除后仍会保留所有权。

DELETE /webResource/resourceID

请参阅 delete 请求示例。
getToken

获取要放置在已验证用户网站上的验证令牌。

请求正文：

  • identifier：网站网址或域名。
  • type：要验证的资源类型。可能的值：SITE、INET_DOMAIN。
  • verificationMethod：验证网站时使用的方法。可能的值：FILE、META、ANALYTICS、TAG_MANAGER、DNS_TXT、DNS_CNAME

POST /token

请参阅 getToken 请求示例。

API 调用示例

本部分假定您（开发者）也是经过身份验证的用户，当您首次使用自己的测试数据试用该 API 时即是如此。

验证新网站

如需验证网站，请按以下步骤操作：

  1. 首先，通过调用 getToken 请求验证令牌。
  2. 使用您选择的任意方法将令牌放到您的网站上。
  3. 让 Google 使用插入操作验证该网站归您所有。

getToken（需要授权）

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token

请求：

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token
Content-Type: application/json

{
  "verificationMethod": "FILE",
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

响应：

{
  "token": "google12cfc68677988bb4.html",
  "method": "FILE"
}

插入（需要授权）

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token

请求：

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token
Content-Type: application/json

{
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

响应：

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

检索经过验证的网络资源的信息

您可以通过调用 list 来检索已验证网站和网域的完整列表。您可以通过调用 get 检索单个网络资源的信息。

列表（需要授权）

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

请求：

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

响应：

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

获取（需要授权）

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

请求：

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

响应：

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

修改验证信息

您可以通过调用 update 来委托和撤消所有权。您可以调用 delete 移除自己的所有权。

更新（需要授权）

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

请求：

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token
Content-Type: application/json

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

响应：

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

删除（需要授权）

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

请求：

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

响应：

HTTP 204（无内容）状态代码，表示成功。