使用 Indexing API 的前提条件

在开始使用 Indexing API 之前,需要先执行以下几项操作(如果尚未完成):

为客户端创建一个项目

在向 Indexing API 发送请求之前,您需要告知 Google 您的客户端并激活对 Indexing API 的访问权限。要完成这项操作,您可以使用 Google API 控制台创建一个项目(该项目是设置和 API 访问信息的命名集合),然后注册您的应用。

开始使用 Indexing API 之前,您需要先使用设置工具在 Google API 控制台中创建项目、启用 Indexing API 以及创建凭据。

创建服务帐号

  1. 打开服务帐号页面。如果看到提示,请选择项目。
  2. 点击 创建服务帐号,并输入服务帐号的名称和说明。您可以使用默认服务帐号 ID,也可以选择其他唯一的帐号 ID。完成后,点击创建
  3. 后面的服务帐号权限(可选)部分无需设置。点击继续
  4. 向用户授予访问此服务帐号的权限屏幕上,向下滚动到创建密钥部分。点击 创建密钥
  5. 在随即显示的侧面板中,选择密钥的格式:建议使用 JSON
  6. 点击创建。您的新公钥/私钥对随后会生成并下载到您的计算机上;该密钥仅此一份。要了解如何安全地存储密钥,请参阅管理服务帐号密钥
  7. 点击私钥已保存到您的计算机对话框中的关闭,然后点击完成以返回服务帐号表格。

将您的服务帐号添加为网站所有者

要将您的服务帐号添加为网站所有者,请执行以下操作:

  1. 首先使用 Search Console 证明您是该网站的所有者,然后
  2. 将您的服务帐号添加为所有者。

1. 证明您是网站的所有者

使用 Search Console 验证网站所有权。 您可以使用 Search Console 支持的任何验证方法。您可以创建网域资源 (example.com) 或网址前缀资源(https://example.com 或 https://example.com/some/path/)来表示您的网站 (请注意,网站在 Search Console 中称为“资源”)。

2. 向您的服务帐号授予所有者状态

接下来,将您的服务帐号添加为(代理)网站所有者:

  1. 打开网站站长中心
  2. 点击您已验证所有权的资源。
  3. 经过验证的所有者列表中,点击添加所有者
  4. 提供作为代理所有者的服务帐号电子邮件地址。您可以在以下两个位置找到您的服务帐号电子邮件地址:
    • 您在创建项目时下载的 JSON 私钥中的 client_email 字段。
    • Developers Console 中“服务帐号”视图的服务帐号 ID 列。
    电子邮件地址的格式如下:
    my-service-account@project-name.google.com.iam.gserviceaccount.com
    例如:my-service-account@test-project-42.google.com.iam.gserviceaccount.com

获取访问令牌

对 Indexing API 的每次调用都必须使用 OAuth 令牌进行身份验证,该令牌以您的私钥交换获得。每个令牌只在一段时间内有效。 您可以通过 Google 提供的 API 客户端库获取多种语言的 Oauth 令牌。

要求

在向 Indexing API 提交请求时,您的请求必须满足以下条件:

  1. 使用 https://www.googleapis.com/auth/indexing 作为作用域。
  2. 使用使用 API 中介绍的端点之一。
  3. 包含服务帐号访问令牌
  4. 按照使用 API 中的说明定义请求的正文。

示例

以下示例说明了如何获取 OAuth 访问令牌:

Python

使用 Python 版 Google API 客户端库获取 OAuth 令牌:

from oauth2client.service_account import ServiceAccountCredentials
import httplib2

SCOPES = [ "https://www.googleapis.com/auth/indexing" ]
ENDPOINT = "https://indexing.googleapis.com/v3/urlNotifications:publish"

# service_account_file.json is the private key that you created for your service account.
JSON_KEY_FILE = "service_account_file.json"

credentials = ServiceAccountCredentials.from_json_keyfile_name(JSON_KEY_FILE, scopes=SCOPES)

http = credentials.authorize(httplib2.Http())

# Define contents here as a JSON string.
# This example shows a simple update request.
# Other types of requests are described in the next step.

content = """{
  \"url\": \"http://example.com/jobs/42\",
  \"type\": \"URL_UPDATED\"
}"""

response, content = http.request(ENDPOINT, method="POST", body=content)

Java

使用 Java 版 API 客户端库获取 OAuth 令牌:

String scopes = "https://www.googleapis.com/auth/indexing";
String endPoint = "https://indexing.googleapis.com/v3/urlNotifications:publish";

JsonFactory jsonFactory = new JacksonFactory();

// service_account_file.json is the private key that you created for your service account.
InputStream in = IOUtils.toInputStream("service_account_file.json");

GoogleCredential credentials =
  GoogleCredential.fromStream(in, this.httpTransport, jsonFactory).createScoped(Collections.singleton(scopes));

GenericUrl genericUrl = new GenericUrl(endPoint);
HttpRequestFactory requestFactory = this.httpTransport.createRequestFactory();

// Define content here. The structure of the content is described in the next step.
String content = "{"
  + "\"url\": \"http://example.com/jobs/42\","
  + "\"type\": \"URL_UPDATED\","
  + "}";

HttpRequest request =
  requestFactory.buildPostRequest(genericUrl, ByteArrayContent.fromString("application/json", content));

credentials.initialize(request);
HttpResponse response = request.execute();
int statusCode = response.getStatusCode();

PHP

使用 PHP 版 API 客户端库获取 OAuth 令牌:

require_once 'google-api-php-client/vendor/autoload.php';

$client = new Google_Client();

// service_account_file.json is the private key that you created for your service account.
$client->setAuthConfig('service_account_file.json');
$client->addScope('https://www.googleapis.com/auth/indexing');

// Get a Guzzle HTTP Client
$httpClient = $client->authorize();
$endpoint = 'https://indexing.googleapis.com/v3/urlNotifications:publish';

// Define contents here. The structure of the content is described in the next step.
$content = '{
  "url": "http://example.com/jobs/42",
  "type": "URL_UPDATED"
}';

$response = $httpClient->post($endpoint, [ 'body' => $content ]);
$status_code = $response->getStatusCode();

Node.js

使用 Node.js 客户端库获取 OAuth 令牌:

var request = require("request");
var { google } = require("googleapis");
var key = require("./service_account.json");

const jwtClient = new google.auth.JWT(
  key.client_email,
  null,
  key.private_key,
  ["https://www.googleapis.com/auth/indexing"],
  null
);

jwtClient.authorize(function(err, tokens) {
  if (err) {
    console.log(err);
    return;
  }
  let options = {
    url: "https://indexing.googleapis.com/v3/urlNotifications:publish",
    method: "POST",
    // Your options, which must include the Content-Type and auth headers
    headers: {
      "Content-Type": "application/json"
    },
    auth: { "bearer": tokens.access_token },
    // Define contents here. The structure of the content is described in the next step.
    json: {
      "url": "http://example.com/jobs/42",
      "type": "URL_UPDATED"
    }
  };
  request(options, function (error, response, body) {
    // Handle the response
    console.log(body);
  });
});

除了演示如何获取令牌之外,这些示例还演示了您可以添加请求消息正文的位置。要了解您可以发出哪些类型的调用以及这些调用的消息正文结构,请参阅使用 Indexing API