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。
或者,您也可以从以下位置访问 gcloud
和 curl
:
使用 Cloud Shell 管理 Google Cloud 控制台。
创建复合索引
如需创建新的复合索引,请使用 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
将请求正文保存在名为 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
将请求正文保存在名为 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
API 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
执行以下命令:
$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
API 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
执行以下命令:
$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
API 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
执行以下命令:
$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
API 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" } ] }