API REST cơ sở dữ liệu Firebase

Sử dụng API

Bạn có thể sử dụng bất kỳ URL cơ sở dữ liệu thời gian thực Firebase nào làm điểm cuối REST. Tất cả những gì bạn cần làm là thêm .json vào cuối URL và gửi yêu cầu từ ứng dụng khách HTTPS yêu thích của bạn.

HTTPS là bắt buộc. Firebase chỉ phản hồi lưu lượng được mã hóa để dữ liệu của bạn được an toàn.

NHẬN - Đọc dữ liệu

Dữ liệu từ Cơ sở dữ liệu thời gian thực của bạn có thể được đọc bằng cách đưa ra yêu cầu HTTP GET tới điểm cuối. Ví dụ sau minh họa cách bạn có thể truy xuất tên người dùng mà trước đó bạn đã lưu trữ trong Cơ sở dữ liệu thời gian thực.

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

Yêu cầu thành công được biểu thị bằng mã trạng thái HTTP 200 OK . Phản hồi chứa dữ liệu được liên kết với đường dẫn trong yêu cầu GET .

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

PUT - Ghi dữ liệu

Bạn có thể ghi dữ liệu bằng yêu cầu PUT .

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

Yêu cầu thành công được biểu thị bằng mã trạng thái HTTP 200 OK . Phản hồi chứa dữ liệu được chỉ định trong yêu cầu PUT .

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

POST - Đẩy dữ liệu

Để thực hiện tương đương với phương thức push() của JavaScript (xem Danh sách dữ liệu ), bạn có thể đưa ra yêu cầu POST .

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

Yêu cầu thành công được biểu thị bằng mã trạng thái HTTP 200 OK . Phản hồi chứa tên con của dữ liệu mới được chỉ định trong yêu cầu POST .

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

PATCH - Cập nhật dữ liệu

Bạn có thể cập nhật các phần tử con cụ thể tại một vị trí mà không cần ghi đè dữ liệu hiện có bằng yêu cầu PATCH . Những phần tử con được đặt tên trong dữ liệu được ghi bằng PATCH sẽ bị ghi đè, nhưng những phần tử con bị bỏ qua sẽ không bị xóa. Điều này tương đương với hàm JavaScript update() .

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

Yêu cầu thành công được biểu thị bằng mã trạng thái HTTP 200 OK . Phản hồi chứa dữ liệu được chỉ định trong yêu cầu PATCH .

{ "last": "Jones" }

DELETE - Xóa dữ liệu

Bạn có thể xóa dữ liệu bằng yêu cầu DELETE :

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

Yêu cầu DELETE thành công được biểu thị bằng mã trạng thái HTTP 200 OK với phản hồi chứa JSON null .

Ghi đè phương thức

Nếu bạn thực hiện lệnh gọi REST từ trình duyệt không hỗ trợ các phương thức trước đó, bạn có thể ghi đè phương thức yêu cầu bằng cách thực hiện yêu cầu POST và đặt phương thức của bạn bằng cách sử dụng tiêu đề yêu cầu X-HTTP-Method-Override .

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

Bạn cũng có thể sử dụng tham số truy vấn x-http-method-override .

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

Yêu cầu có điều kiện

Các yêu cầu có điều kiện, REST tương đương với các hoạt động giao dịch SDK, cập nhật dữ liệu theo một điều kiện nhất định. Xem tổng quan về quy trình làm việc và tìm hiểu thêm về các yêu cầu có điều kiện cho REST trong Saving Data .

Thẻ Firebase ET

Firebase ETag là mã định danh duy nhất cho dữ liệu hiện tại tại một vị trí được chỉ định. Nếu dữ liệu thay đổi ở vị trí đó thì ETag cũng thay đổi. Firebase ETag phải được chỉ định trong tiêu đề cho yêu cầu REST ban đầu (thường là GET , nhưng có thể là bất kỳ thứ gì khác ngoài PATCH ).

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

nếu khớp

Điều kiện if-match chỉ định giá trị ETag cho dữ liệu bạn muốn cập nhật. Nếu bạn sử dụng điều kiện, Cơ sở dữ liệu thời gian thực chỉ hoàn thành các yêu cầu trong đó ETag được chỉ định trong yêu cầu ghi khớp với ETag của dữ liệu hiện có trong cơ sở dữ liệu. Tìm nạp ETag tại một vị trí có yêu cầu ETag Firebase. Nếu bạn muốn ghi đè bất kỳ vị trí nào không có giá trị, hãy sử dụng null_etag .

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

Phản hồi dự kiến

Bảng sau đây cung cấp thông tin tổng quan về phản hồi dự kiến ​​cho từng loại yêu cầu, dựa trên kết quả khớp ETag.

Loại yêu cầu 'X-Firebase-ETag: đúng' ETag phù hợp
if_match: <matching etag>
ETag không khớp
if_match: <no matching etag>
LẤY Trạng thái/Nội dung phản hồi 200: "<data_at_path>" 400: "...không được hỗ trợ.." 400: "...không được hỗ trợ.."
Tiêu đề đã thêm Thẻ ET: <ETag_of_data> không áp dụng không áp dụng
ĐẶT Trạng thái/Nội dung phản hồi 200: "<put_data>" 200: "<put_data>" 412: "...Thẻ Etag không khớp.."
Tiêu đề đã thêm Thẻ ET: <ETag_of_put_data> không áp dụng Thẻ ET: <database_ETag>
BƯU KIỆN Trạng thái/Nội dung phản hồi 200: "<post_data>" 400: "...không được hỗ trợ.." 400: "...không được hỗ trợ.."
Tiêu đề đã thêm Thẻ ET: <ETag_of_post_data> không áp dụng không áp dụng
Trạng thái/Nội dung phản hồi 400: "...không được hỗ trợ.." 400: "...không được hỗ trợ.." 400: "...không được hỗ trợ.."
Tiêu đề đã thêm không áp dụng không áp dụng không áp dụng
XÓA BỎ Trạng thái/Nội dung phản hồi 200: vô giá trị 200: "<data_after_put>" 412: "...Thẻ Etag không khớp.."
Tiêu đề đã thêm Thẻ ET: <ETag_of_null> không áp dụng Thẻ ET: <database_ETag>

Tham số truy vấn

API REST của cơ sở dữ liệu Firebase chấp nhận các tham số và giá trị truy vấn sau:

truy cập thẻ

Được hỗ trợ bởi tất cả các loại yêu cầu. Xác thực yêu cầu này để cho phép truy cập vào dữ liệu được bảo vệ bởi Quy tắc bảo mật cơ sở dữ liệu thời gian thực của Firebase. Xem tài liệu xác thực REST để biết chi tiết.

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

nông

Đây là một tính năng nâng cao, được thiết kế để giúp bạn làm việc với các tập dữ liệu lớn mà không cần phải tải xuống mọi thứ. Đặt giá trị này thành true để giới hạn độ sâu của dữ liệu được trả về tại một vị trí. Nếu dữ liệu tại vị trí đó là dữ liệu gốc JSON (chuỗi, số hoặc boolean), giá trị của nó sẽ được trả về đơn giản. Nếu ảnh chụp nhanh dữ liệu tại vị trí đó là một đối tượng JSON thì các giá trị cho mỗi khóa sẽ bị cắt ngắn thành true .

Tranh luận Phương thức REST Sự miêu tả
nông LẤY Giới hạn độ sâu của phản hồi.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Lưu ý rằng shallow không thể trộn lẫn với bất kỳ tham số truy vấn nào khác.

in

Định dạng dữ liệu được trả về trong phản hồi từ máy chủ.

Tranh luận Phương thức REST Sự miêu tả
đẹp NHẬN, ĐẶT, ĐĂNG, VÁ, XÓA Xem dữ liệu ở định dạng mà con người có thể đọc được.
im lặng NHẬN, ĐẶT, ĐĂNG, VÁ Được sử dụng để chặn đầu ra từ máy chủ khi ghi dữ liệu. Phản hồi kết quả sẽ trống và được biểu thị bằng mã trạng thái HTTP 204 No Content .
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'

gọi lại

Chỉ được hỗ trợ bởi GET . Để thực hiện lệnh gọi REST từ trình duyệt web trên nhiều miền, bạn có thể sử dụng JSONP để gói phản hồi trong hàm gọi lại JavaScript. Thêm callback= để API REST bao bọc dữ liệu được trả về trong hàm gọi lại mà bạn chỉ định.

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

định dạng

Nếu được đặt thành export , máy chủ sẽ mã hóa mức độ ưu tiên trong phản hồi.

Tranh luận Phương thức REST Sự miêu tả
xuất khẩu LẤY Bao gồm thông tin ưu tiên trong phản hồi.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

Tải xuống

Chỉ được hỗ trợ bởi GET . Nếu bạn muốn kích hoạt tải xuống tệp dữ liệu của mình từ trình duyệt web, hãy thêm download= . Điều này khiến dịch vụ REST thêm các tiêu đề thích hợp để trình duyệt biết lưu dữ liệu vào một tệp.

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

hết giờ

Sử dụng điều này để giới hạn thời gian đọc ở phía máy chủ. Nếu yêu cầu đọc không hoàn thành trong thời gian quy định, yêu cầu đó sẽ kết thúc với lỗi HTTP 400. Điều này đặc biệt hữu ích khi bạn mong đợi một lượng dữ liệu nhỏ được truyền đi và không muốn đợi quá lâu để tìm nạp một cây con có tiềm năng rất lớn. Thời gian đọc thực tế có thể thay đổi tùy theo kích thước dữ liệu và bộ nhớ đệm.

Chỉ định timeouts bằng định dạng sau: 3ms , 3s hoặc 3min , kèm theo số và đơn vị. Nếu không được chỉ định, timeout tối đa là 15min sẽ được áp dụng. Nếu timeout không dương hoặc vượt quá mức tối đa, yêu cầu sẽ bị từ chối với lỗi HTTP 400.

viếtSizeLimit

Để giới hạn kích thước của một lần ghi, bạn có thể chỉ định tham số truy vấn writeSizeLimittiny (target=1s), small (target=10s), medium (target=30s), large (target=60s). Cơ sở dữ liệu thời gian thực ước tính kích thước của mỗi yêu cầu ghi và hủy bỏ các yêu cầu sẽ mất nhiều thời gian hơn thời gian mục tiêu.

Nếu bạn chỉ định unlimited , cho phép ghi đặc biệt lớn (với tải trọng lên tới 256 MB), có khả năng chặn các yêu cầu tiếp theo trong khi cơ sở dữ liệu xử lý hoạt động hiện tại. Việc ghi không thể bị hủy khi chúng đã đến máy chủ.

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

Bạn sẽ thấy thông báo lỗi sau nếu nội dung ghi quá lớn:

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

Ngoài ra, bạn có thể đặt defaultWriteSizeLimit cho toàn bộ phiên bản cơ sở dữ liệu bằng Firebase CLI. Giới hạn này áp dụng cho tất cả các yêu cầu, bao gồm cả những yêu cầu từ SDK. Cơ sở dữ liệu mới được tạo với defaultWriteSizeLimit được đặt large . Bạn không thể đặt defaultWriteSizeLimit thành tiny bằng Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

đặt bởi

Xem phần trong hướng dẫn về dữ liệu được sắp xếp để biết thêm thông tin.

limitToFirst, limitToLast, startAt, endAt, bằngTo

Xem phần trong hướng dẫn lọc dữ liệu để biết thêm thông tin.

Truyền phát từ API REST

Điểm cuối Firebase REST hỗ trợ giao thức Sự kiện EventSource / Server-Sent . Để truyền phát các thay đổi đến một vị trí trong Cơ sở dữ liệu thời gian thực, bạn cần thực hiện một số điều:

  • Đặt tiêu đề Chấp nhận của khách hàng thành "text/event-stream"
  • Tôn trọng chuyển hướng HTTP, đặc biệt là mã trạng thái HTTP 307
  • Nếu vị trí yêu cầu quyền đọc, bạn phải bao gồm tham số auth

Đổi lại, máy chủ sẽ gửi các sự kiện được đặt tên dưới dạng trạng thái của dữ liệu tại các thay đổi URL được yêu cầu. Cấu trúc của các thông báo này tuân theo giao thức EventSource .

event: event name
data: JSON encoded data payload

Máy chủ có thể gửi các sự kiện sau:

đặt

Dữ liệu được mã hóa JSON là một đối tượng có hai khóa: pathdata . Khóa đường dẫn trỏ đến một vị trí liên quan đến URL yêu cầu. Máy khách nên thay thế tất cả dữ liệu tại vị trí đó trong bộ đệm của nó bằng dữ liệu .

Dữ liệu được mã hóa JSON là một đối tượng có hai khóa: pathdata . Khóa đường dẫn trỏ đến một vị trí liên quan đến URL yêu cầu. Đối với mỗi khóa trong data , máy khách nên thay thế khóa tương ứng trong bộ đệm của nó bằng dữ liệu cho khóa đó trong tin nhắn.

cố sống đi

Dữ liệu cho sự kiện này là null . Không cần thực hiện hành động nào.

Hủy bỏ

Một số lỗi không mong muốn có thể gửi sự kiện `canc` và chấm dứt kết nối. Nguyên nhân được mô tả trong dữ liệu được cung cấp cho sự kiện này. Một số nguyên nhân tiềm ẩn như sau: 1. Quy tắc bảo mật cơ sở dữ liệu thời gian thực Firebase không còn cho phép đọc tại vị trí được yêu cầu. Mô tả `dữ liệu` cho nguyên nhân này là "Quyền bị từ chối". 2. Một thao tác ghi đã kích hoạt trình truyền phát sự kiện gửi một cây JSON lớn vượt quá giới hạn của chúng tôi là 512 MB. `dữ liệu` cho nguyên nhân này là "Tải trọng được chỉ định quá lớn, vui lòng yêu cầu một vị trí có ít dữ liệu hơn."

auth_revoked

Dữ liệu cho sự kiện này là một chuỗi cho biết thông tin xác thực đã hết hạn. Sự kiện này được gửi khi thông số auth được cung cấp không còn hợp lệ.

Dưới đây là tập hợp ví dụ về các sự kiện mà máy chủ có thể gửi:

// 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}}

Ưu tiên

Thông tin ưu tiên cho một vị trí có thể được tham chiếu bằng "đứa con ảo" có tên .priority . Bạn có thể đọc mức độ ưu tiên với các yêu cầu GET và viết chúng bằng các yêu cầu PUT . Ví dụ: yêu cầu sau truy xuất mức độ ưu tiên của nút users/tom :

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

Để ghi mức độ ưu tiên và dữ liệu cùng lúc, bạn có thể thêm phần tử con .priority vào tải trọng JSON:

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

Để ghi mức độ ưu tiên và giá trị nguyên thủy (ví dụ: một chuỗi) cùng lúc, bạn có thể thêm một phần tử con .priority và đặt giá trị nguyên thủy vào một phần .value :

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

Điều này viết "Tom" với mức độ ưu tiên là 1.0 . Mức độ ưu tiên có thể được đưa vào ở bất kỳ mức độ nào trong tải trọng JSON.

Giá trị máy chủ

Bạn có thể ghi các giá trị máy chủ tại một vị trí bằng cách sử dụng giá trị giữ chỗ là một đối tượng có một khóa .sv . Giá trị cho khóa đó là loại giá trị máy chủ bạn muốn đặt. Ví dụ: yêu cầu sau đặt giá trị của nút thành dấu thời gian hiện tại của máy chủ Firebase:

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

Bạn cũng có thể viết mức độ ưu tiên bằng cách sử dụng các giá trị máy chủ, sử dụng đường dẫn "con ảo" đã lưu ý ở trên.

Các giá trị máy chủ được hỗ trợ bao gồm:

Giá trị máy chủ
dấu thời gian Thời gian kể từ kỷ nguyên UNIX, tính bằng mili giây.
tăng Cung cấp một giá trị delta số nguyên hoặc dấu phẩy động, ở dạng { ".sv": {"increment": <delta_value> }} , để tăng dần giá trị cơ sở dữ liệu hiện tại. Nếu dữ liệu chưa tồn tại, bản cập nhật sẽ đặt dữ liệu về giá trị delta. Nếu một trong hai giá trị delta hoặc dữ liệu hiện có là số dấu phẩy động thì cả hai giá trị sẽ được hiểu là số dấu phẩy động và được áp dụng ở mặt sau dưới dạng giá trị kép. Số học kép và biểu diễn các giá trị kép tuân theo ngữ nghĩa của IEEE 754. Nếu có tràn số nguyên dương/âm, tổng được tính là gấp đôi.

Truy xuất và cập nhật Quy tắc bảo mật cơ sở dữ liệu thời gian thực Firebase

API REST cũng có thể được sử dụng để truy xuất và cập nhật Quy tắc bảo mật cơ sở dữ liệu thời gian thực Firebase cho dự án Firebase của bạn. Bạn sẽ cần bí mật của dự án Firebase mà bạn có thể tìm thấy trong bảng Tài khoản dịch vụ trong cài đặt dự án Firebase của mình.

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'

Xác thực yêu cầu

Theo mặc định, các yêu cầu REST được thực thi mà không cần xác thực và sẽ chỉ thành công nếu Quy tắc cơ sở dữ liệu thời gian thực cho phép quyền truy cập đọc hoặc ghi công khai vào dữ liệu. Để xác thực yêu cầu của bạn, hãy sử dụng tham số truy vấn access_token= hoặc auth= .

Tìm hiểu thêm về xác thực thông qua API REST trong Xác thực yêu cầu REST .

Điều kiện lỗi

API REST của cơ sở dữ liệu Firebase có thể trả về các mã lỗi sau.

Mã trạng thái HTTP
400 yêu cầu xấu

Một trong các tình trạng lỗi sau:

  • Không thể phân tích dữ liệu PUT hoặc POST .
  • Thiếu dữ liệu PUT hoặc POST .
  • Yêu cầu cố gắng PUT hoặc POST dữ liệu quá lớn.
  • Lệnh gọi API REST chứa tên con không hợp lệ như một phần của đường dẫn.
  • Đường dẫn gọi API REST quá dài.
  • Yêu cầu chứa giá trị máy chủ không được nhận dạng.
  • Chỉ mục cho truy vấn không được xác định trong Quy tắc bảo mật cơ sở dữ liệu thời gian thực Firebase của bạn.
  • Yêu cầu không hỗ trợ một trong các tham số truy vấn được chỉ định.
  • Yêu cầu trộn các tham số truy vấn với yêu cầu GET nông.
401 trái phép

Một trong các tình trạng lỗi sau:

404 không tìm thấy Không tìm thấy Cơ sở dữ liệu thời gian thực được chỉ định.
Lỗi máy chủ nội bộ 500 Máy chủ trả về lỗi. Xem thông báo lỗi để biết thêm chi tiết.
Lỗi 503: Dịch vụ không khả dụng Cơ sở dữ liệu thời gian thực Firebase được chỉ định tạm thời không khả dụng, điều đó có nghĩa là yêu cầu chưa được thực hiện.
412 Điều kiện tiên quyết không thành công Giá trị ETag được chỉ định của yêu cầu trong tiêu đề if-match không khớp với giá trị của máy chủ.