调用 API

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

调用 API

请求格式

大多数受支持的网站验证操作会直接映射到 REST HTTP 动词(GETPOSTPUTDELETE),如 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。用于此请求的验证方法。可能的值:FILEMETAANALYTICSTAG_MANAGERDNS_TXTDNS_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:要验证的资源类型。可能的值:SITEINET_DOMAIN
  • verificationMethod:验证网站时使用的方法。可能的值:FILEMETAANALYTICSTAG_MANAGERDNS_TXTDNS_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(无内容)状态代码,表示成功。