Firebase 데이터베이스 REST API

API 사용

모든 Firebase 실시간 데이터베이스 URL을 REST 엔드포인트로 사용할 수 있습니다. 여러분이 해야 할 일은 URL 끝에 .json 추가하고 즐겨 사용하는 HTTPS 클라이언트에서 요청을 보내는 것뿐입니다.

HTTPS가 필요합니다. Firebase는 데이터를 안전하게 유지하기 위해 암호화된 트래픽에만 응답합니다.

GET - 데이터 읽기

엔드포인트에 HTTP GET 요청을 보내 실시간 데이터베이스의 데이터를 읽을 수 있습니다. 다음 예에서는 이전에 실시간 데이터베이스에 저장한 사용자 이름을 검색하는 방법을 보여줍니다.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 GET 요청의 경로와 연결된 데이터가 포함됩니다.

{ "first": "Jack", "last": "Sparrow" }

PUT - 데이터 쓰기

PUT 요청으로 데이터를 쓸 수 있습니다.

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 PUT 요청에 지정된 데이터가 포함됩니다.

{ "first": "Jack", "last": "Sparrow" }

POST - 데이터 푸시

JavaScript push() 메서드( 데이터 목록 참조)와 동등한 작업을 수행하려면 POST 요청을 실행할 수 있습니다.

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 POST 요청에 지정된 새 데이터의 하위 이름이 포함됩니다.

{ "name": "-INOQPH-aV_psbk3ZXEX" }

패치 - 데이터 업데이트

PATCH 요청을 사용하면 기존 데이터를 덮어쓰지 않고 특정 위치의 하위 항목을 업데이트할 수 있습니다. PATCH 로 기록 중인 데이터의 명명된 하위 항목은 덮어쓰지만, 생략된 하위 항목은 삭제되지 않습니다. 이는 JavaScript update() 함수와 동일합니다.

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 PATCH 요청에 지정된 데이터가 포함됩니다.

{ "last": "Jones" }

DELETE - 데이터 제거

DELETE 요청으로 데이터를 삭제할 수 있습니다.

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

성공적인 DELETE 요청은 JSON null 포함하는 응답과 함께 200 OK HTTP 상태 코드로 표시됩니다.

메소드 재정의

이전 메서드를 지원하지 않는 브라우저에서 REST 호출을 수행하는 경우 POST 요청을 만들고 X-HTTP-Method-Override 요청 헤더를 사용하여 메서드를 설정하여 요청 메서드를 재정의할 수 있습니다.

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

x-http-method-override 쿼리 매개변수를 사용할 수도 있습니다.

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

조건부 요청

SDK 트랜잭션 작업에 해당하는 REST인 조건부 요청은 특정 조건에 따라 데이터를 업데이트합니다. 데이터 저장 에서 워크플로우 개요를 확인하고 REST에 대한 조건부 요청에 대해 자세히 알아보세요.

Firebase ETag

Firebase ETag는 지정된 위치에 있는 현재 데이터의 고유 식별자입니다. 해당 위치에서 데이터가 변경되면 ETag도 변경됩니다. Firebase ETag는 초기 REST 요청의 헤더에 지정되어야 합니다(일반적으로 GET 이지만 PATCH 이외의 것일 수도 있음).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

일치하는 경우

if-match 조건은 업데이트할 데이터의 ETag 값을 지정합니다. 조건을 사용하면 실시간 데이터베이스는 쓰기 요청에 지정된 ETag가 데이터베이스에 있는 기존 데이터의 ETag와 일치하는 요청만 완료합니다. Firebase ETag 요청이 있는 위치에서 ETag를 가져옵니다. null인 위치를 덮어쓰려면 null_etag 사용하세요.

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

예상되는 응답

다음 표에서는 ETag 일치를 기반으로 각 요청 유형에 대해 예상되는 응답의 개요를 제공합니다.

요청 유형 'X-Firebase-ETag: 참' ETag 일치
if_match: <matching etag>
ETag가 일치하지 않습니다
if_match: <no matching etag>
얻다 응답현황/내용 200: "<데이터_at_경로>" 400: "...지원되지 않습니다.." 400: "...지원되지 않습니다.."
추가된 헤더 ETag: <ETag_of_data> 해당 없음 해당 없음
놓다 응답현황/내용 200: "<put_data>" 200: "<put_data>" 412: "...ETag 불일치.."
추가된 헤더 ETag: <ETag_of_put_data> 해당 없음 ETag: <database_ETag>
우편 응답현황/내용 200: "<포스트_데이터>" 400: "...지원되지 않습니다.." 400: "...지원되지 않습니다.."
추가된 헤더 ETag: <ETag_of_post_data> 해당 없음 해당 없음
반점 응답현황/내용 400: "...지원되지 않습니다.." 400: "...지원되지 않습니다.." 400: "...지원되지 않습니다.."
추가된 헤더 해당 없음 해당 없음 해당 없음
삭제 응답현황/내용 200: 널 200: "<데이터_이후_푸트>" 412: "...ETag 불일치.."
추가된 헤더 ETag: <ETag_of_null> 해당 없음 ETag: <database_ETag>

쿼리 매개변수

Firebase 데이터베이스 REST API는 다음 쿼리 매개변수와 값을 허용합니다.

액세스 토큰

모든 요청 유형에서 지원됩니다. Firebase 실시간 데이터베이스 보안 규칙으로 보호되는 데이터에 대한 액세스를 허용하려면 이 요청을 인증합니다. 자세한 내용은 REST 인증 설명서를 참조하세요.

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

얕은

이는 모든 것을 다운로드할 필요 없이 대규모 데이터 세트로 작업할 수 있도록 설계된 고급 기능입니다. 위치에 반환되는 데이터의 깊이를 제한하려면 이를 true 로 설정합니다. 해당 위치의 데이터가 JSON 기본 형식(문자열, 숫자 또는 부울)인 경우 해당 값이 반환됩니다. 해당 위치의 데이터 스냅샷이 JSON 객체인 경우 각 키의 값은 true 로 잘립니다.

인수 REST 방법 설명
얕은 얻다 응답의 깊이를 제한하십시오.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

shallow 는 다른 쿼리 매개변수와 혼합될 수 없습니다.

인쇄

서버의 응답으로 반환된 데이터의 형식을 지정합니다.

인수 REST 방법 설명
예쁜 가져오기, 넣기, 게시, 패치, 삭제 사람이 읽을 수 있는 형식으로 데이터를 봅니다.
조용한 가져오기, 넣기, 게시, 패치 데이터를 쓸 때 서버의 출력을 억제하는 데 사용됩니다. 결과 응답은 비어 있으며 204 No Content HTTP 상태 코드로 표시됩니다.
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

콜백

GET 에서만 지원됩니다. 도메인 전체의 웹 브라우저에서 REST 호출을 수행하려면 JSONP를 사용하여 JavaScript 콜백 함수로 응답을 래핑할 수 있습니다. REST API가 반환된 데이터를 사용자가 지정한 콜백 함수로 래핑하도록 하려면 callback= 추가하세요.

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

체재

export 로 설정하면 서버는 응답의 우선순위를 인코딩합니다.

인수 REST 방법 설명
내보내다 얻다 응답에 우선순위 정보를 포함하십시오.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

다운로드

GET 에서만 지원됩니다. 웹 브라우저에서 데이터의 파일 다운로드를 실행하려면 download= 추가하세요. 이로 인해 REST 서비스는 브라우저가 데이터를 파일에 저장하는 방법을 알 수 있도록 적절한 헤더를 추가합니다.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

시간 초과

이를 사용하여 서버 측에서 읽기에 걸리는 시간을 제한합니다. 읽기 요청이 할당된 시간 내에 완료되지 않으면 HTTP 400 오류로 종료됩니다. 이는 작은 데이터 전송이 예상되고 잠재적으로 큰 하위 트리를 가져오는 데 너무 오래 기다리지 않으려는 경우 특히 유용합니다. 실제 읽기 시간은 데이터 크기 및 캐싱에 따라 달라질 수 있습니다.

숫자 및 단위와 함께 3ms , 3s 또는 3min 형식을 사용하여 timeouts 지정합니다. 지정하지 않으면 최대 15mintimeout 적용됩니다. timeout 양수가 아니거나 최대값을 초과하는 경우 HTTP 400 오류와 함께 요청이 거부됩니다.

쓰기 크기 제한

쓰기 크기를 제한하려면 writeSizeLimit 쿼리 매개변수를 tiny (대상=1초), small (대상=10초), medium (대상=30초), large (대상=60초)로 지정할 수 있습니다. 실시간 데이터베이스는 각 쓰기 요청의 크기를 추정하고 목표 시간보다 오래 걸리는 요청을 중단합니다.

unlimited 지정하면 예외적으로 큰 쓰기(최대 256MB 페이로드 포함)가 허용되어 데이터베이스가 현재 작업을 처리하는 동안 후속 요청이 차단될 가능성이 있습니다. 쓰기가 서버에 도달하면 취소할 수 없습니다.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

쓰기 용량이 너무 크면 다음 오류 메시지가 표시됩니다.

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

또한 Firebase CLI를 사용하여 전체 데이터베이스 인스턴스에 대해 defaultWriteSizeLimit 설정할 수 있습니다. 이 제한은 SDK의 요청을 포함한 모든 요청에 ​​적용됩니다. defaultWriteSizeLimit large 로 설정된 새 데이터베이스가 생성됩니다. Firebase CLI를 사용하여 defaultWriteSizeLimit tiny 설정할 수 없습니다.

firebase database:settings:set defaultWriteSizeLimit large

주문

자세한 내용은 정렬된 데이터 가이드의 섹션을 참조하세요.

limitToFirst,limitToLast,startAt,endAt,equalTo

자세한 내용은 데이터 필터링 가이드의 섹션을 참조하세요.

REST API에서 스트리밍

Firebase REST 엔드포인트는 EventSource/서버 전송 이벤트 프로토콜을 지원합니다. 실시간 데이터베이스의 단일 위치로 변경 사항을 스트리밍하려면 다음 몇 가지 작업을 수행해야 합니다.

  • 클라이언트의 Accept 헤더를 "text/event-stream" 으로 설정합니다.
  • HTTP 리디렉션, 특히 HTTP 상태 코드 307을 존중합니다.
  • 해당 위치에 읽기 권한이 필요한 경우 auth 매개변수를 포함해야 합니다.

그 대가로 서버는 요청된 URL의 데이터 상태가 변경됨에 따라 명명된 이벤트를 보냅니다. 이러한 메시지의 구조는 EventSource 프로토콜을 따릅니다.

event: event name
data: JSON encoded data payload

서버는 다음 이벤트를 보낼 수 있습니다.

놓다

JSON으로 인코딩된 데이터는 pathdata 라는 두 개의 키가 있는 객체입니다. 경로 키는 요청 URL과 관련된 위치를 가리킵니다. 클라이언트는 캐시의 해당 위치에 있는 모든 데이터를 data 로 바꿔야 합니다.

반점

JSON으로 인코딩된 데이터는 pathdata 라는 두 개의 키가 있는 객체입니다. 경로 키는 요청 URL과 관련된 위치를 가리킵니다. data 의 각 키에 대해 클라이언트는 캐시의 해당 키를 메시지의 해당 키에 대한 데이터로 바꿔야 합니다.

살아 유지

이 이벤트의 데이터는 null 입니다. 조치가 필요하지 않습니다.

취소

예상치 못한 오류로 인해 '취소' 이벤트가 전송되고 연결이 종료될 수 있습니다. 원인은 이 이벤트에 대해 제공된 데이터에 설명되어 있습니다. 몇 가지 잠재적인 원인은 다음과 같습니다. 1. Firebase 실시간 데이터베이스 보안 규칙이 더 이상 요청된 위치에서 읽기를 허용하지 않습니다. 이 원인에 대한 `데이터` 설명은 "권한이 거부되었습니다."입니다. 2. 쓰기로 인해 제한인 512MB를 초과하는 대규모 JSON 트리를 전송하는 이벤트 스트리머가 트리거되었습니다. 이에 대한 `데이터`는 "지정한 페이로드가 너무 큽니다. 데이터가 적은 위치를 요청하세요."입니다.

인증_취소됨

이 이벤트의 데이터는 자격 증명이 만료되었음을 나타내는 문자열입니다. 이 이벤트는 제공된 auth 매개변수가 더 이상 유효하지 않을 때 전송됩니다.

다음은 서버가 보낼 수 있는 이벤트 세트의 예입니다.

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}

// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}

// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

우선순위

위치에 대한 우선순위 정보는 .priority 라는 "가상 하위 항목"을 통해 참조될 수 있습니다. GET 요청으로 우선순위를 읽고 PUT 요청으로 쓸 수 있습니다. 예를 들어, 다음 요청은 users/tom 노드의 우선순위를 검색합니다.

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

우선순위와 데이터를 동시에 작성하려면 JSON 페이로드에 .priority 하위 항목을 추가하면 됩니다.

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

우선순위와 기본 값(예: 문자열)을 동시에 작성하려면 .priority 하위 항목을 추가하고 기본 값을 .value 하위 항목에 넣을 수 있습니다.

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

그러면 우선순위가 1.0"Tom" 작성됩니다. 우선순위는 JSON 페이로드의 모든 깊이에 포함될 수 있습니다.

서버 가치

단일 .sv 키가 있는 개체인 자리 표시자 값을 사용하여 특정 위치에 서버 값을 쓸 수 있습니다. 해당 키의 값은 설정하려는 서버 값의 유형입니다. 예를 들어 다음 요청은 노드 값을 Firebase 서버의 현재 타임스탬프로 설정합니다.

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

위에서 언급한 "가상 하위" 경로를 사용하여 서버 값을 사용하여 우선순위를 작성할 수도 있습니다.

지원되는 서버 값은 다음과 같습니다.

서버 가치
타임스탬프 UNIX 시대 이후의 시간(밀리초)입니다.
증가 현재 데이터베이스 값을 원자적으로 증가시키는 { ".sv": {"increment": <delta_value> }} 형식으로 정수 또는 부동 소수점 델타 값을 제공합니다. 데이터가 아직 존재하지 않는 경우 업데이트는 데이터를 델타 값으로 설정합니다. 델타 값이나 기존 데이터 중 하나가 부동 소수점 숫자인 경우 두 값 모두 부동 소수점 숫자로 해석되어 백엔드에 double 값으로 적용됩니다. 이중 산술 및 이중 값 표현은 IEEE 754 의미 체계를 따릅니다. 양수/음수 정수 오버플로가 있는 경우 합계는 double로 계산됩니다.

Firebase 실시간 데이터베이스 보안 규칙 검색 및 업데이트

REST API를 사용하여 Firebase 프로젝트에 대한 Firebase 실시간 데이터베이스 보안 규칙을 검색하고 업데이트할 수도 있습니다. Firebase 프로젝트 설정의 서비스 계정 패널에서 찾을 수 있는 Firebase 프로젝트의 비밀번호가 필요합니다.

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

요청 인증

기본적으로 REST 요청은 인증 없이 실행되며 실시간 데이터베이스 규칙이 데이터에 대한 공개 읽기 또는 쓰기 액세스를 허용하는 경우에만 성공합니다. 요청을 인증하려면 access_token= 또는 auth= 쿼리 매개변수를 사용하세요.

REST 요청 인증 에서 REST API를 통한 인증에 대해 자세히 알아보세요.

오류 조건

Firebase 데이터베이스 REST API는 다음 오류 코드를 반환할 수 있습니다.

HTTP 상태 코드
400 잘못된 요청

다음 오류 조건 중 하나:

  • PUT 또는 POST 데이터를 구문 분석할 수 없습니다.
  • PUT 또는 POST 데이터가 누락되었습니다.
  • 요청이 너무 큰 데이터를 PUT 또는 POST 하려고 시도합니다.
  • REST API 호출에는 경로의 일부로 잘못된 하위 이름이 포함되어 있습니다.
  • REST API 호출 경로가 너무 깁니다.
  • 요청에 인식할 수 없는 서버 값이 포함되어 있습니다.
  • 쿼리 색인이 Firebase 실시간 데이터베이스 보안 규칙 에 정의되어 있지 않습니다.
  • 요청이 지정된 쿼리 매개변수 중 하나를 지원하지 않습니다.
  • 요청은 쿼리 매개변수와 얕은 GET 요청을 혼합합니다.
401 무단

다음 오류 조건 중 하나:

404 찾을 수 없음 지정된 실시간 데이터베이스를 찾을 수 없습니다.
500 내부 서버 오류 서버에서 오류를 반환했습니다. 자세한 내용은 오류 메시지를 참조하세요.
503 서비스를 사용할 수 없습니다. 지정된 Firebase 실시간 데이터베이스를 일시적으로 사용할 수 없습니다. 이는 요청이 시도되지 않았음을 의미합니다.
412 전제조건 실패 if-match 헤더에 있는 요청의 지정된 ETag 값이 서버 값과 일치하지 않습니다.