Sử dụng API
Bạn có thể sử dụng bất kỳ URL nào của Cơ sở dữ liệu theo thời gian thực của Firebase làm điểm cuối REST. Tất cả những gì bạn cần
cần làm là nối .json vào cuối URL và gửi một yêu cầu
từ ứng dụng HTTPS mà bạn yêu thích.
Giao thức HTTPS là bắt buộc. Firebase chỉ phản hồi lưu lượng truy cập đã mã hoá để dữ liệu của bạn vẫn được an toàn.
GET – Đọc dữ liệu
Hệ thống có thể đọc dữ liệu trên Realtime Database bằng cách phát một giao thức HTTP
Yêu cầu GET đến một điểm cuối. Ví dụ sau đây
cho thấy cách bạn có thể truy xuất
mà bạn đã lưu trữ trước đó trong Realtime Database.
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ột HTTP 200 OK
mã trạng thái. Phản hồi chứa dữ liệu liên quan đến
đườ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ột HTTP 200 OK
mã trạng thái. 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
Để hoàn tất mã tương đương với 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 trạng thái HTTP 200 OK
. Phản hồi có 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 thông tin về các phần tử cụ thể tại một vị trí mà không cần ghi đè
dữ liệu hiện có bằng cách sử dụng yêu cầu PATCH. Trẻ em được đặt tên trong
dữ liệu đang được ghi bằng PATCH sẽ bị ghi đè, nhưng vẫn được bỏ qua
phần tử con sẽ không bị xoá. Điều này tương đương với JavaScript
Hàm 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 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" }
XÓA – Đang xoá dữ liệu
Bạn có thể xoá 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ừ mộ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 tạo
Yêu cầu POST và đặt phương thức của bạn bằng cách sử dụng
tiêu đề của 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, phiên bản tương đương của Kiến trúc chuyển trạng thái đại diện (REST) cho hoạt động giao dịch của 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 công việc và tìm hiểu thêm về yêu cầu có điều kiện cho REST trong mục Save Data (Lưu dữ liệu).
Thẻ ETag Firebase
Firebase ETag là giá trị nhận dạng duy nhất cho dữ liệu hiện tại ở một vị trí cụ thể. Nếu
khi dữ liệu thay đổi tại vị trí đó, thì ETag cũng thay đổi. Bạn phải chỉ định thẻ ETag Firebase trong
cho yêu cầu REST ban đầu (thường là
GET nhưng có thể là bất kỳ giá trị nào 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 mà bạn muốn cập nhật.
Nếu bạn dùng điều kiện, Realtime Database chỉ hoàn tất các yêu cầu mà 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 vị trí có yêu cầu Firebase ETag. Nếu bạn muốn ghi đè bất kỳ vị trí nào
rỗng, sử dụng null_etag.
curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'
Số lượt phản hồi dự kiến
Bảng sau đây cung cấp thông tin tổng quan về các phản hồi dự kiến cho mỗi loại yêu cầu, dựa trên kết quả trùng khớp ETag.
| Loại yêu cầu | "X-Firebase-ETag: true" | ETag khớp với if_match: <matching etag> |
ETag không khớp với if_match: <no matching etag> |
|
|---|---|---|---|---|
| TẢI | 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ẻ ETag: <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: "...ETag không khớp.." |
| Tiêu đề đã thêm | Thẻ ETag: <ETag_of_put_data> | Không áp dụng | Thẻ ETag: <database_ETag> | |
| SAU KHI TRIỂN KHAI | 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ẻ ETag: <ETag_of_post_data> | Không áp dụng | Không áp dụng | |
| CHỨC DANH | 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 có | Không áp dụng | |
| XOÁ | Trạng thái/nội dung phản hồi | 200: rỗng | 200: "<data_after_put>" | 412: "...Thẻ ETag không khớp.." |
| Tiêu đề đã thêm | Thẻ ETag: <ETag_of_null> | Không áp dụng | Thẻ ETag: <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ố truy vấn sau và giá trị:
access_token
Được tất cả các loại yêu cầu hỗ trợ. Xác thực yêu cầu này để cho phép quyền truy cập vào dữ liệu được bảo vệ bằng Firebase Realtime Database Security Rules. Hãy xem Tài liệu xác thực REST để biết thông tin chi tiết.
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
nông
Đây là tính năng nâng cao, được thiết kế để giúp bạn làm việc với
mà không cần tải mọi thứ xuống. Đặt 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), thì giá trị của nó sẽ chỉ được trả về. Nếu
Tổng quan nhanh dữ liệu tại vị trí này là một đối tượng JSON,
giá trị cho mỗi khóa sẽ được cắt ngắn thành true.
| Đối số | Phương thức REST | Mô tả |
|---|---|---|
| vàng | NHẬN | Giới hạn độ sâu của phản hồi. |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
Lưu ý rằng không thể kết hợp shallow với bất kỳ truy vấn nào khác
tham số.
in
Định dạng dữ liệu được trả về trong phản hồi từ máy chủ.
| Đối số | Phương thức REST | Mô tả |
|---|---|---|
| Xinh | GET, PUT, POST, PATCH, DELETE | Xem dữ liệu ở định dạng mà con người có thể đọc được. |
| tắt tiếng | GET, PUT, POST, PATCH |
Dùng để chặn đầu ra từ máy chủ khi ghi dữ liệu.
Phản hồi thu được 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'
số gọi lại
Chỉ do GET hỗ trợ. Cách thực hiện cuộc 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 một JavaScript
hàm callback. Thêm callback= để gói API REST
dữ liệu được trả về trong hàm callback 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 bạn đặt thành export, máy chủ sẽ mã hoá các mức độ ưu tiên trong
của bạn.
| Đối số | Phương thức REST | Mô tả |
|---|---|---|
| xuất | NHẬN | Thêm thông tin ưu tiên vào câu trả lời. |
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'
tải xuống
Chỉ do GET hỗ trợ. Nếu bạn muốn kích hoạt một tệp
tải dữ liệu của bạn xuống từ trình duyệt web, hãy thêm download=.
Việc này sẽ khiến dịch vụ REST thêm tiêu đề thích hợp để
trình duyệt biết cần lưu dữ liệu vào tệp.
curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'
tạm ngừng
Sử dụng tính năng này để giới hạn thời gian đọc ở phía máy chủ. Nếu một lượt đọc không kết thúc trong thời gian quy định mà sẽ chấm dứt bằng một HTTP Lỗi 400. Điều này đặc biệt hữu ích khi bạn muốn chuyển một lượng dữ liệu nhỏ và không muốn đợi quá lâu để tìm nạp cây con có khả năng rất lớn. Thực tế thời gian đọc có thể khác nhau tuỳ theo kích thước dữ liệu và bộ nhớ đệm.
Hãy 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
đã chỉ định, timeout tối đa của 15min sẽ là
áp dụng. Nếu timeout không dương hoặc vượt quá giá trị tối đa,
yêu cầu sẽ bị từ chối kèm theo lỗi HTTP 400.
ghi Giới hạn kích thước
Để giới hạn kích thước của một lượt ghi, bạn có thể chỉ định tham số truy vấn
writeSizeLimit là
tiny (mục tiêu=1 giây), small (mục tiêu=10 giây),
medium (mục tiêu=30 giây), large (mục tiêu=60 giây).
Cơ sở dữ liệu theo thời gian thực ước tính kích thước của mỗi yêu cầu ghi và huỷ
sẽ mất nhiều thời gian hơn thời gian mục tiêu.
Nếu bạn chỉ định unlimited, thì lượt ghi cực lớn (với tải trọng tối đa 256 MB)
được phép, có thể 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. Bạn không thể huỷ thao tác ghi sau khi đế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 giá trị 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ộ cơ sở dữ liệu
thực thể bằng cách sử dụng Giao diện dòng lệnh (CLI) của Firebase. Giới hạn này áp dụng cho tất cả các yêu cầu, kể cả yêu cầu từ SDK.
Các cơ sở dữ liệu mới sẽ được tạo bằng cách đặt defaultWriteSizeLimit thành large.
Bạn không thể đặt defaultWriteSizeLimit thành tiny bằng giao diện dòng lệnh (CLI) của Firebase.
firebase database:settings:set defaultWriteSizeLimit large
orderBy
Xem phần này trong hướng dẫn về dữ liệu được đặt hàng để biết thêm thông tin.
limitToFirst, limitToLast, startAt, endAt, equalsTo
Xem phần này trong hướng dẫn về lọc dữ liệu cho biết thêm thông tin.
Truyền trực tuyến từ API REST
Điểm cuối REST của Firebase hỗ trợ Sự kiện EventSource / Sự kiện do máy chủ gửi giao thức. Để phát trực tuyến các thay đổi đối với một vị trí duy nhất trong Realtime Database của bạn: bạn cần làm một số việc:
-
Đặt tiêu đề Chấp nhận của ứng dụng thành
"text/event-stream" - Tuân thủ chuyển hướng HTTP, cụ thể là mã trạng thái HTTP 307
-
Nếu vị trí đó yêu cầu quyền để đọc, bạn phải cung cấp
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 về URL được yêu cầu. Cấu trúc của các thông báo này tuân thủ
giao thức EventSource.
event: event name data: JSON encoded data payload
Máy chủ có thể gửi những sự kiện sau:
đặt
Dữ liệu được mã hoá JSON là một đối tượng có hai khoá: path và dữ liệu. Đường dẫn trỏ đến một so với URL yêu cầu. Khách hàng nên thay thế tất cả dữ liệu tại vị trí đó trong bộ nhớ đệm kèm theo dữ liệu.
bản vá
Dữ liệu được mã hoá JSON là một đối tượng có hai khoá: path và dữ liệu. Đường dẫn trỏ đến một so với URL yêu cầu. Đối với mỗi khoá trong data, thì ứng dụng khách sẽ thay thế thuộc tính khoá tương ứng trong bộ nhớ đệm với dữ liệu cho khoá đó trong thông báo.
duy trì hoạt động
Dữ liệu của sự kiện này là null. Bạn không cần phải làm gì khác.
hủy
Một số lỗi không mong muốn có thể gửi sự kiện "cancel" 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. Có thể kể đến một số nguyên nhân như sau: 1. Firebase Realtime Database Security Rules không còn cho phép đọc ở vị trí được yêu cầu nữa. Chiến lược phát hành đĩa đơn Nội dung mô tả "dữ liệu" cho nguyên nhân này là "Quyền bị từ chối". 2. Một lượt ghi đã kích hoạt một trình truyền trực tuyến 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, 512MB. "Dữ liệu" của nguyên nhân này là "Tải trọng đã chỉ định quá lớn, vui lòng yêu cầu với ít dữ liệu hơn."
bị thu hồi xác thực
Dữ liệu cho sự kiện này là một chuỗi cho biết rằng thông tin xác thực
đã hết hạn. Sự kiện này được gửi khi auth đã cung cấp
tham số không còn hợp lệ.
Dưới đây là ví dụ về một tập hợp 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
Bạn có thể tham chiếu thông tin ưu tiên cho một vị trí bằng
"trẻ ảo" có tên là .priority. Bạn có thể đọc các mức độ ưu tiên bằng
GET yêu cầu và viết chúng bằng PUT yêu cầu.
Ví dụ: yêu cầu sau đây 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 một lúc, bạn có thể thêm
.priority phần tử con với 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ị gốc (ví dụ: một chuỗi) cùng một lúc,
bạn có thể thêm phần tử con .priority và đặt giá trị gốc
trong thành phần con .value:
curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'
Thao tác này ghi "Tom" với mức độ ưu tiên là 1.0.
Bạn có thể đưa các mức độ ưu tiên ở mọi độ sâu trong tải trọng JSON.
Giá trị của 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ị phần giữ chỗ
là đối tượng có một khoá .sv duy nhất. Giá trị của khoá đó là
loại giá trị máy chủ mà bạn muốn đặt. Ví dụ: như sau
yêu cầu đặt giá trị của nút thành giá trị hiện tại của máy chủ Firebase
timestamp [dấu_thời_gian]:
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'
Bạn cũng có thể ghi mức độ ưu tiên bằng cách sử dụng các giá trị máy chủ, bằng "trẻ ảo" đường dẫn nêu trên.
Sau đây là các giá trị máy chủ được hỗ trợ:
| Giá trị máy chủ | |
|---|---|
| dấu thời gian | Thời gian kể từ thời gian bắt đầu của hệ thống UNIX, tính bằng mili giây. |
| mức tăng | Cung cấp một giá trị delta số nguyên hoặc dấu phẩy động dưới dạng
{ ".sv": {"increment": <delta_value> }}, để xác định theo tỷ lệ
làm tăng giá trị cơ sở dữ liệu hiện tại. Nếu chưa có dữ liệu, nội dung cập nhật sẽ đặt
dữ liệu cho giá trị delta. Nếu một trong hai giá trị delta hoặc dữ liệu hiện tại là giá trị nổi
dấu phẩy động, cả hai giá trị sẽ được hiểu là số thực và áp dụng cho
chương trình phụ trợ dưới dạng giá trị kép. Số học kép và cách 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 sẽ được tính
thành kiểu kép. |
Đang truy xuất và cập nhật Firebase Realtime Database Security Rules
API REST cũng có thể được dùng để truy xuất và cập nhật Firebase Realtime Database Security Rules cho dự án Firebase của bạn. Bạn sẽ cần mã thông báo bí mật của dự án Firebase. bạn có thể tìm thấy trong Bảng điều khiển Tài khoản dịch vụ trong dự án Firebase của bạn cài đặt.
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
Realtime Database Quy tắc cho phép quyền đọ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ề việc xác thực thông qua API REST trong Xác thực yêu cầu REST.
Các điều kiện về 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 không hợp lệ |
Một trong các điều kiện lỗi sau:
|
| 401 Không được phép |
Một trong các điều kiện lỗi sau:
|
| 404 Không tìm thấy | Không tìm thấy Realtime Database được chỉ định. |
| 500 Lỗi máy chủ nội bộ | Máy chủ trả về một lỗi. Hãy xem thông báo lỗi để biết thêm chi tiết. |
| 503 Dịch vụ không hoạt động | Cơ sở dữ liệu theo thời gian thực của Firebase được chỉ định tạm thời không hoạt động, thì có nghĩa là yêu cầu chưa được thử. |
| 412 Không đáp ứng được điều kiện tiên quyết | 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ủ. |