使用 Indexing API

總覽

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

傳送要求給 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==

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