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ợpif_match: <matching etag> | ETag không khớpif_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 | |
VÁ | 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 writeSizeLimit
là tiny
(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: path và data . 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 .
vá
Dữ liệu được mã hóa JSON là một đối tượng có hai khóa: path và data . 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:
|
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ủ. |
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2024-03-20 UTC.