Cloud Firestore REST API 사용

Cloud Firestore를 사용하는 가장 쉬운 방법은 기본 클라이언트 라이브러리 중 하나를 사용하는 것이지만, 경우에 따라서는 REST API를 직접 호출하는 방법이 유용할 수 있습니다.

다음과 같은 사용 사례에서는 REST API가 유용할 수 있습니다.

  • 사물 인터넷(IoT) 기기와 같이 리소스가 제한되어 전체 클라이언트 라이브러리를 실행할 수 없는 환경에서 Cloud Firestore에 액세스할 때
  • 데이터베이스 관리를 자동화하거나 상세한 데이터베이스 메타데이터를 검색할 때

gRPC 지원 언어를 사용한다면 REST API 대신 RPC API를 사용해 보세요.

인증 및 승인

Cloud Firestore REST API는 인증에 Firebase Authentication ID 토큰이나 Google ID OAuth 2.0 토큰을 허용합니다. 개발자가 제공한 토큰이 요청의 승인에 영향을 미칩니다.

  • 애플리케이션 사용자의 요청을 인증하려면 Firebase ID 토큰을 사용합니다. 이러한 요청의 경우 Cloud Firestore는 Cloud Firestore Security Rules을 사용하여 요청이 승인되었는지 확인합니다.

  • 데이터베이스 관리 요청과 같은 애플리케이션의 요청을 인증하려면 Google ID OAuth 2.0 토큰과 서비스 계정을 사용합니다. 이러한 요청의 경우 Cloud Firestore는 Identity and Access Management(IAM)를 사용하여 요청이 승인되었는지 확인합니다.

Firebase ID 토큰 다루기

두 가지 방법으로 Firebase ID 토큰을 획득할 수 있습니다.

사용자의 Firebase ID 토큰을 가져오면 사용자를 대신하여 요청할 수 있습니다.

Firebase ID 토큰으로 인증된 요청과 인증되지 않은 요청의 경우 Cloud Firestore는 Cloud Firestore Security Rules을 사용하여 요청이 승인되었는지 확인합니다.

Google ID OAuth 2.0 토큰 다루기

Google API 클라이언트 라이브러리로 서비스 계정을 사용하거나 서버 애플리케이션에 서버용 OAuth 2.0 사용에 나온 단계에 따라 액세스 토큰을 생성할 수 있습니다. gcloud 명령줄 도구와 gcloud auth application-default print-access-token 명령어를 사용하여 토큰을 생성할 수도 있습니다.

Cloud Firestore REST API로 요청을 보내려면 토큰 범위가 다음과 같아야 합니다.

  • https://www.googleapis.com/auth/datastore

서비스 계정과 Google ID OAuth 2.0 토큰으로 요청을 인증하면 Cloud Firestore는 개별 사용자 대신 애플리케이션을 대신하여 요청하는 것이라고 간주합니다. Cloud Firestore에서는 이러한 요청이 보안 규칙을 무시할 수 있습니다. 대신 Cloud Firestore는 IAM을 사용하여 요청이 승인되었는지 확인합니다.

Cloud Firestore IAM 역할을 할당하여 서비스 계정의 액세스 권한을 제어할 수 있습니다.

액세스 토큰으로 인증

Firebase ID 토큰이나 Google ID OAuth 2.0 토큰을 획득한 후 Bearer {YOUR_TOKEN}로 설정한 Authorization 헤더로 Cloud Firestore 엔드포인트에 전달합니다.

REST 호출

모든 REST API 엔드포인트는 기본 URL https://firestore.googleapis.com/v1/에 존재합니다.

YOUR_PROJECT_ID 프로젝트의 cities 컬렉션에 ID가 LA인 문서의 경로를 만들려면 다음과 같은 구조를 사용합니다.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

이 경로와 상호작용하려면 기본 API URL과 결합합니다.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

REST API 실험에 가장 좋은 방법은 API Explorer를 사용하는 것입니다. 자동으로 Google ID OAuth 2.0 토큰이 생성되어 API를 검사할 수 있습니다.

메서드

다음은 가장 중요한 메서드 그룹 두 가지에 대한 간단한 설명입니다. 전체 목록은 REST API 참조 또는 API 탐색기를 참조하세요.

v1.projects.databases.documents

문서에 대해 CRUD 작업을 수행합니다. 방법은 데이터 추가 또는 데이터 가져오기 가이드에 설명된 내용과 유사합니다.

v1.projects.databases.collectionGroups.indexes

색인 새로 만들기, 기존 색인 사용 중지, 현재 색인 모두 나열과 같은 색인 관련 작업을 수행합니다. 데이터 구조 이전을 자동화하거나 프로젝트 간에 색인을 동기화하는 데 유용합니다.

또한 특정 문서의 모든 필드나 하위 컬렉션 목록과 같은 문서 메타데이터를 검색할 수 있습니다.

오류 코드

Cloud Firestore 요청이 성공하면 Cloud Firestore API가 HTTP 200 OK 상태 코드와 요청된 데이터를 반환합니다. 요청이 실패하면 Cloud Firestore API가 HTTP 4xx 또는 5xx 상태 코드와 오류 정보가 포함된 응답을 반환합니다.

다음 표에는 각 오류 코드에 대한 권장 작업이 나와 있습니다. 이러한 코드는 Cloud Firestore REST API와 RPC API에 적용됩니다. Cloud Firestore 및 클라이언트 라이브러리는 이러한 같은 오류 코드를 반환하지 않을 수 있습니다.

표준 오류 코드 설명 권장 작업
ABORTED 요청이 다른 요청과 충돌했습니다. 비트랜잭션 커밋의 경우:
요청을 다시 시도하거나 데이터 모델을 다시 구조화하여 경합을 줄입니다.

트랜잭션에 포함된 요청의 경우:
전체 트랜잭션을 다시 시도하거나 데이터 모델을 다시 구조화하여 경합을 줄입니다.
ALREADY_EXISTS 요청이 이미 존재하는 문서를 만들려고 시도했습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
DEADLINE_EXCEEDED 요청을 처리하는 Cloud Firestore 서버가 기한을 초과했습니다. 지수 백오프를 사용하여 다시 시도하세요.
FAILED_PRECONDITION 요청이 전제 조건 중 하나를 충족하지 않았습니다. 예를 들어 쿼리 요청에 아직 정의되지 않은 색인이 필요할 수 있습니다. 오류 응답의 메시지 필드에서 실패한 전제 조건을 확인하세요. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
INTERNAL Cloud Firestore 서버에서 오류를 반환했습니다. 이 요청을 두 번 이상 재시도하지 마세요.
INVALID_ARGUMENT 요청 매개변수에 잘못된 값이 포함되어 있습니다. 오류 응답의 메시지 필드에서 잘못된 값을 확인하세요. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
NOT_FOUND 요청이 존재하지 않는 문서를 업데이트하려고 했습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
PERMISSION_DENIED 사용자에게 이 요청을 보낼 권한이 없습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
RESOURCE_EXHAUSTED 프로젝트가 할당량 또는 리전/멀티 리전 용량을 초과했습니다. 프로젝트 할당량을 초과하지 않았는지 확인하세요. 프로젝트 할당량을 초과한 경우 문제를 해결하지 않은 상태로 다시 시도하지 마세요.

그렇지 않으면 지수 백오프를 사용하여 다시 시도하세요.
UNAUTHENTICATED 요청에 유효한 사용자 인증 정보가 포함되지 않았습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
UNAVAILABLE Cloud Firestore 서버에서 오류를 반환했습니다. 지수 백오프를 사용하여 다시 시도하세요.