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
インデックスの読み取り専用アクセス（取得と一覧表示）の場合は、次のいずれかのロールを付与します。
- roles/viewer
- roles/datastore.user
- roles/datastore.viewer

こうしたロールの割り当ての詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

始める前に

以下の curl と PowerShell の例では、Google Cloud CLI（Google Cloud CLI）を使用してリクエストを認証します。これらの例をローカルで実行するには、Google Cloud CLI をインストールして初期化します。

また、Cloud Shell を使用して Google Cloud Console から gcloud と curl にアクセスすることもできます。

Cloud Shell の起動

複合インデックスの作成

新しい複合インデックスを作成するには、projects.indexes.create メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

project-id: プロジェクト ID
kind: インデックス登録するエンティティの種類
include-ancestors: 祖先クエリ（NONE または ALL_ANCESTORS）をサポートするために、エンティティの祖先をインデックスに含めるかどうか
property-name: インデックス登録するプロパティ。2 つ以上のプロパティを指定する必要があります
index-direction: 各プロパティの並べ替え順序（ASCENDING または DESCENDING）

HTTP メソッドと URL:

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

API Explorer

リクエスト本文をコピーして、メソッドのリファレンスページを開きます。ページの右側に [API 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 メソッドと URL:

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

メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

次のような 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 メソッドと URL:

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

成功したことを示すステータスコード（2xx）と空のレスポンスが返されます。

すべての複合インデックスの一覧表示

Datastore モードのデータベースのすべての複合インデックスを一覧表示するには、projects.indexes.list メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

project-id: プロジェクト ID

HTTP メソッドと URL:

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

次のような 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

API Explorer

インデックス ステータスの取得

curl

PowerShell

API Explorer

インデックスの状態

複合インデックスの削除

curl

PowerShell

API Explorer

すべての複合インデックスの一覧表示

curl

PowerShell

API Explorer

インデックスステータスの取得