使用 Indexing API

總覽

您可以使用 Indexing API 要求 Google 更新或移除 Google 索引中的網頁,但這些要求必須指明網頁的所在位置。您也可以針對您傳送給 Google 的通知取得相關狀態。目前 Indexing API 只能用於檢索含有徵人啟事即時串流結構化資料的網頁。

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

下列範例示範您可以對 Indexing API 執行的動作:

更新網址

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

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

GET https://indexing.googleapis.com/v3/urlNotifications/metadata

參數

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

欄位
url

必填

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

type

必填

您提交的通知類型。

規範

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

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

更新網址

如要通知 Google 有新網址需要檢索,或是先前提交的網址內容有所更動,請按照下列步驟操作:

  1. 向下列端點提交 POST 要求:
    POST 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. 您所需的配額可能會超過預設配額。如要查看您目前擁有的配額或要求更多配額,請參閱配額頁面。

移除網址

如果您從伺服器中刪除了特定網頁,請通知 Google 將該網頁從索引中移除,這樣系統才不會一再嘗試重新檢索該網址。提交移除要求之前,請務必先將該網頁從您的伺服器中移除,並確認該網址會傳回 404 或 410 狀態碼。

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

  1. 向下列端點提交 POST 要求:
    POST 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
    GET 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==

詳情請參閱傳送批次要求