使用 Indexing API

總覽

您可以使用 Indexing API 要求 Google 更新或移除 Google 索引中的網頁， 但這些要求必須指明網頁的所在位置。您也可以針對您傳送給 Google 的通知取得相關狀態。目前，Indexing API 只能用於檢索在 VideoObject 中嵌入 BroadcastEvent 或 JobPosting 的網頁。

傳送要求給 Indexing API 時，請指明獨立網頁的位置，以通知 Google 檢索該網頁或將該網頁從索引中移除。

下方範例呈現了您可以透過 Indexing API 執行的動作：

更新網址 

Send the following HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish endpoint
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_UPDATED"
}
 移除網址 

Send the following HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish endpoint
{
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
 取得通知狀態 

Send a HTTP GET request to https://indexing.googleapis.com/v3/urlNotifications/metadata endpoint

參數

下列資料表說明了所有方法 (更新及移除網址) 所需的欄位：

欄位
url

必要

您想更新或移除的項目的完整位置。
type

必要

您提交的通知類型。

規範

提出更新及移除網址的要求時，須遵循下列規範。

  • 所有傳送至 https://indexing.googleapis.com/v3/UrlNotifications:publish 的呼叫都「必須」使用「application/json」做為 Content-Type 標頭。
  • 單一更新要求的主體中只能提交一個網址，或者，您可以按照傳送批次索引要求一節的說明，提交最多包含 100 個要求的批次要求。
  • 本頁範例中的要求主體是存取權杖範例中所用的 content 變數值。

更新網址

如果您有新的網址需要 Google 檢索，或是向 Google 傳達先前提交的網址有更新內容，請按照下列步驟操作：

  1. 向下列端點提交 POST 要求： 
    Send a HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish
  2. 在要求主體中使用下列語法指明網頁位置： 
    {
  "url": "content_location",
  "type": "URL_UPDATED"
}
  3. Google 會對成功傳送的 Indexing API 呼叫回傳 HTTP 200；收到 HTTP 200 回覆代表 Google 很快就會嘗試重新檢索該網址。回覆主體包含一個 UrlNotificationMetadata 物件，其中的欄位會與通知狀態要求傳回的欄位相對應。
  4. 如果沒有收到 HTTP 200 回應，請參閱 Indexing API 相關錯誤。
  5. 如果網頁的內容有所更動，請另外提交更新通知，這應該會觸發 Google 重新檢索網頁的動作。
  6. 您所需的配額可能會超過預設配額。如要查看您目前擁有的配額或要求更多配額，請參閱配額頁面。

移除網址

當您從伺服器中刪除網頁，或在特定網頁的 <head> 區段中新增 <meta name="robots" content="noindex" /> 標記後，請通知 Google 將該網頁從索引中移除，避免讓系統一再嘗試重新檢索該網頁並為其建立索引。提交移除要求之前，該網址必須傳回 404 或 410 狀態碼，或者網頁中必須含有 <meta name="robots" content="noindex" /> meta 標記。

如需要求 Google 將特定網頁從索引中移除，請按照下列步驟操作：

  1. 向下列端點提交 POST 要求： 
    Send a HTTP POST request to https://indexing.googleapis.com/v3/urlNotifications:publish
  2. 在要求主體中使用下列語法指明目標移除網址： 
    {
  "url": "content_location",
  "type": "URL_DELETED"
}

    例如：

    {
  "url": "https://careers.google.com/jobs/google/technical-writer",
  "type": "URL_DELETED"
}
  3. Google 會對成功傳送的 Indexing API 呼叫回傳 HTTP 200；收到 HTTP 200 回覆代表 Google 會將該網址從索引中移除。回覆主體包含一個 UrlNotificationMetadata 物件，其中的欄位會與通知狀態要求傳回的欄位相對應。
  4. 如果沒有收到 HTTP 200 回應，請參閱 Indexing API 相關錯誤。
  5. 您所需的配額可能會超過預設配額。如要查看您目前擁有的配額或要求更多配額，請參閱配額頁面。

取得通知狀態

您可以使用 Indexing API 查看 Google 最近一次針對特定網址收到各類型通知的時間。GET 要求不會顯示 Google 將網址編入索引或移除網址的時間，只會傳回要求是否已成功提交的訊息。

如要取得通知狀態，請按照下列步驟操作：

  1. 向下列端點提交 GET 要求。您指定的網址必須為網址編碼格式，例如將 : (冒號) 替換為 %3A，並將 / (正斜線) 替換為 %2F。
    Send a HTTP GET request to https://indexing.googleapis.com/v3/urlNotifications/metadata?url=url-encoded_url

    例如：

    GET https://indexing.googleapis.com/v3/urlNotifications/metadata?url=https%3A%2F%2Fcareers.google.com%2Fjobs%2Fgoogle%2Ftechnical-writer
  2. Indexing API 會回覆 HTTP 200 訊息及內含通知詳細資料的酬載。以下範例呈現了包含更新及刪除通知相關資訊的回應主體： 
    {
  url: "http://foo.com",
  latest_update: {
    type: "URL_UPDATED",
    notify_time: "2017-07-31T19:30:54.524457662Z"
  },
  latest_remove: {
    type: "URL_DELETED",
    notify_time: "2017-08-31T19:30:54.524457662Z"
  }
}
  3. 如果沒有收到 HTTP 200 回應，請參閱 Indexing API 相關錯誤。
  4. 您所需的配額可能會超過預設配額。如要查看您目前擁有的配額或要求更多配額，請參閱配額頁面。

傳送批次索引要求

如要減少用戶端需進行的 HTTP 連線數，您最多可以將要傳送至 Indexing API 的 100 個呼叫合併為一個 HTTP 要求，也就是由多個部分組成的要求，又稱為「批次要求」。

向 Indexing API 傳送批次要求時，請使用下列端點：

https://indexing.googleapis.com/batch

批次要求的主體包含多個部分，每個部分本身都是一個完整的 HTTP 要求，具有自己的動詞、標頭和主體。批次要求中的每個部分大小都不得超過 1 MB。

為了方便您傳送批次要求，Google 的 API 用戶端程式庫支援批次處理功能。如要進一步瞭解如何使用用戶端程式庫進行批次處理，請參閱以下各個程式語言的專屬頁面：

如果使用上述頁面中的批次處理樣本，您可能必須根據取得存取權杖一節提及的實作條件更新程式碼。

下列批次要求訊息主體範例包含一則更新通知和一則移除通知：

POST /batch HTTP/1.1
Host: indexing.googleapis.com
Content-Length: content_length
Content-Type: multipart/mixed; boundary="===============7330845974216740156=="
Authorization: Bearer oauth2_token

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+2>

POST /v3/urlNotifications:publish [1]
Content-Type: application/json
accept: application/json
content-length: 58

{ "url": "http://example.com/jobs/42", "type": "URL_UPDATED" }
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1>

POST /v3/urlNotifications:publish [2]
Content-Type: application/json
accept: application/json
content-length: 75

{ "url": "http://example.com/widgets/1", "type": "URL_UPDATED" }
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+3>

POST /v3/urlNotifications:publish [3]
Content-Type: application/json
accept: application/json
content-length: 58

{ "url": "http://example.com/jobs/43", "type": "URL_DELETED" }
--===============7330845974216740156==

詳情請參閱傳送批次要求一文。