REST API でのインデックスの構成

このページでは、Datastore モードの REST API を使用して Datastore モードの複合インデックスを作成、削除、一覧表示する方法について説明します。

gcloud コマンドライン ツールを使用すると、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 の例では、gcloud コマンドライン ツール(Cloud SDK)を使用してリクエストを認証します。これらの例をローカルで実行するには、Cloud SDK をインストールして初期化します。

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

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

リクエスト本文を 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

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

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

成功したことを示すステータス コード(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

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

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