REST API로 색인 구성

이 페이지에서는 Datastore 모드 REST API를 사용하여 Datastore 모드 복합 색인을 만들고, 삭제하고, 나열하는 방법을 설명합니다.

Google Cloud CLI는 Datastore 모드 REST API에 액세스하고 복합 색인을 관리하는 편리한 방법을 제공합니다. 하지만 Datastore 모드 REST API에 직접 액세스하여 복합 색인을 관리하는 도구를 직접 만들 수도 있습니다. 예를 들어 색인 프로비저닝 및 관리를 자동화하는 도구를 만들 수 있습니다.

인증 및 승인

아래의 Datastore 모드 Firestore 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
색인 읽기 액세스 권한(get 및 list)만 부여하려면 다음 역할 중 하나를 부여합니다.
- 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: 색인을 생성할 속성으로, 둘 이상의 속성을 지정해야 함
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 탐색기

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

다음과 비슷한 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 탐색기

메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 모든 필수 필드를 입력하고 실행을 클릭합니다.

다음과 비슷한 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: 색인을 만들지 못했습니다. 오류의 원인인 데이터를 수정하고 이 색인을 삭제한 다음 색인을 다시 create.
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 탐색기

성공 상태 코드(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 탐색기

다음과 비슷한 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"
  }
 ]
}