本頁面由 Cloud Translation API 翻譯而成。

使用 REST API 設定索引

本頁面說明如何使用 Datastore 模式 REST API，建立、刪除及列出 Datastore 模式複合索引。

Google Cloud CLI 提供便利的方式，可存取 Datastore 模式 REST API 及管理複合索引。不過，您可以直接存取 Datastore 模式 REST API，建立自己的複合索引管理工具。舉例來說，您可以建立工具，自動佈建及管理索引。

驗證及授權

如要存取下列 Firestore (Datastore 模式) REST API 方法，您必須提供 Google OAuth 2.0 存取權杖，並使用下列其中一個範圍驗證要求：

https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform

下方的 cURL 和 PowerShell 範例會使用 gcloud auth print-access-token 指令驗證要求。如要進一步瞭解如何取得存取權杖，請參閱「使用 OAuth 2.0 存取 Google API」。

授權

要求中經過驗證的使用者、群組或服務帳戶必須具備存取 API 方法的授權。如要授權存取索引方法，請指派下列其中一個 Identity and Access Management (IAM) 角色：

如要授予完整的索引讀取和編輯存取權，請指派下列任一角色：
- roles/owner
- roles/editor
- roles/datastore.owner
- roles/datastore.indexAdmin
如要授予索引唯讀存取權 (取得和列出)，請指派下列任一角色：
- roles/viewer
- roles/datastore.user
- roles/datastore.viewer

如要進一步瞭解如何指派這些角色，請參閱授予、變更及撤銷資源的存取權。

事前準備

下方的 curl 和 PowerShell 範例會使用 Google Cloud CLI (Google Cloud CLI) 驗證要求。如要在本機執行這些範例，請安裝並初始化 Google Cloud CLI。

或者，您也可以使用 Cloud Shell，從Google Cloud 控制台存取 gcloud 和 curl。

啟動 Cloud Shell

建立複合式索引

如要建立新的複合索引，請使用 projects.indexes.create 方法。

使用任何要求資料之前，請先替換以下項目：

project-id：您的專案 ID
kind：要建立索引的實體種類
include-ancestors：是否要在索引中加入實體祖先，以支援祖先查詢，可為 NONE 或 ALL_ANCESTORS
property-name：要建立索引的屬性，必須指定兩個以上的屬性
index-direction：每個屬性的排序順序，ASCENDING 或 DESCENDING

HTTP 方法和網址：

POST https://datastore.googleapis.com/v1/projects/project-id/indexes

JSON 要求主體：

{
  "kind": "kind",
  "ancestor": "include-ancestors",
  "properties": [
      {
          "name": "property-name",
          "direction": "index-direction"
      },
      {
          "name": "property-name",
          "direction": "index-direction"
      }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

APIs Explorer

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「Execute」(執行)。

您應該會收到如下的 JSON 回應：

{
  "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIDgxZGVhZDM0ZDc4MS1jMjJhLWQ1ZTQtYmMyNS1iYjY2NWVlZCQadGx1YWZlZAcSMXJoLXJleGVkbmktbmltZGERClIS",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
    "common": {
      "startTime": "2019-12-05T22:27:19.238Z",
      "operationType": "CREATE_INDEX",
      "state": "INITIALIZING"
    },
    "indexId": "CICAgJiUpoMK"
  }
}

取得索引狀態

Datastore 模式會為每個索引指派專屬的索引 ID。您可以使用這個索引 ID，透過 projects.indexes.get 方法取得單一索引的狀態：

使用任何要求資料之前，請先替換以下項目：

project-id：您的專案 ID
index-id：複合式索引 ID

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

您應該會收到如下的 JSON 回應：

{
  "projectId": "project-id",
  "indexId": "index-id",
  "kind": "Task",
  "ancestor": "NONE",
  "properties": [
    {
      "name": "done",
      "direction": "ASCENDING"
    },
    {
      "name": "priority",
      "direction": "ASCENDING"
    }
  ],
  "state": "READY"
}

索引狀態

如要查看進度資訊和錯誤訊息，請參閱索引狀態。索引達到 READY 狀態後，才能用於查詢。可能的索引狀態包括：

CREATING：正在建立索引。
ALREADY_EXISTS：無法完成作業，因為這個索引已存在。
ERROR：索引建立失敗。修正導致錯誤的資料、刪除這個索引，然後再次建立索引。
READY：索引建立完成。索引已可供查詢。

刪除複合式索引

HTTP 方法和網址：

DELETE https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

列出所有複合式索引

如要列出 Datastore 模式資料庫的所有複合索引，請使用 projects.indexes.list 方法。

使用任何要求資料之前，請先替換以下項目：

project-id：您的專案 ID

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/indexes

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

您應該會收到如下的 JSON 回應：

{
 "indexes": [
  {
   "projectId": "project-id",
   "indexId": "CICAgOjXh4EK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "done",
     "direction": "ASCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "READY"
  },
  {
   "projectId": "project-id",
   "indexId": "CICAgNiroIEK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "due-date",
     "direction": "DESCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "CREATING"
  }
 ]
}

使用 REST API 設定索引 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

驗證及授權

授權

事前準備

建立複合式索引

curl

PowerShell

APIs Explorer

取得索引狀態

curl

PowerShell

APIs Explorer

索引狀態

刪除複合式索引

curl

PowerShell

APIs Explorer

列出所有複合式索引

curl

PowerShell

APIs Explorer

使用 REST API 設定索引