使用 REST API 配置索引

本页面介绍如何使用 Datastore 模式 REST API 创建、删除和列出 Datastore 模式复合索引。

Google Cloud CLI 可让您便利地访问 Datastore 模式 REST API 以及管理复合索引。不过，您可以直接访问 Datastore 模式 REST API 来创建自己的工具以管理复合索引。例如，您可以创建工具以自动执行索引预配和管理。

身份验证和授权

如需使用以下 Datastore 模式 REST API 方法访问 Firestore，您必须通过提供具有以下范围之一的 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
如需仅获取索引读取访问权限（get 和 list），请授予以下角色之一：
- roles/viewer
- roles/datastore.user
- roles/datastore.viewer

如需详细了解如何分配这些角色，请参阅授予、更改和撤消对资源的访问权限。

准备工作

下面的 curl 和 PowerShell 示例使用 Google Cloud CLI (Google Cloud CLI) 对请求进行身份验证。如需在本地运行这些示例，请安装并初始化 Google Cloud CLI。

或者，您也可以从 Google Cloud 控制台使用 Cloud Shell 访问 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 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

您应该收到类似以下内容的 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 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行 (Execute)。

您应该会收到一个成功的状态代码 (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"
  }
 ]
}