Mặc dù cách dễ nhất để sử dụng Cloud Firestore là dùng một trong các thư viện ứng dụng gốc, nhưng vẫn có một số trường hợp bạn nên gọi trực tiếp API REST.
API REST có thể hữu ích trong các trường hợp sử dụng sau:
- Truy cập vào Cloud Firestore từ một môi trường bị hạn chế về tài nguyên, chẳng hạn như thiết bị Internet của vạn vật (IoT) mà không thể chạy một thư viện ứng dụng hoàn chỉnh.
- Tự động hoá việc quản trị cơ sở dữ liệu hoặc truy xuất siêu dữ liệu chi tiết của cơ sở dữ liệu.
Nếu bạn đang dùng một ngôn ngữ được hỗ trợ gRPC, hãy cân nhắc dùng RPC API thay vì API REST.
Xác thực và uỷ quyền
Để xác thực, Cloud Firestore REST API chấp nhận mã thông báo mã nhận dạng Xác thực Firebase hoặc mã thông báo Google Identity OAuth 2.0. Mã thông báo mà bạn cung cấp sẽ ảnh hưởng đến việc uỷ quyền của yêu cầu:
Sử dụng mã thông báo mã Firebase để xác thực yêu cầu từ người dùng ứng dụng của bạn. Đối với những yêu cầu này, Cloud Firestore sử dụng Quy tắc bảo mật của Cloud Firestore để xác định xem một yêu cầu có được uỷ quyền hay không.
Sử dụng mã thông báo OAuth 2.0 của Google Identity và tài khoản dịch vụ để xác thực các yêu cầu từ ứng dụng của bạn, chẳng hạn như các yêu cầu quản trị cơ sở dữ liệu. Đối với những yêu cầu này, Cloud Firestore sử dụng giải pháp Quản lý danh tính và quyền truy cập (IAM) để xác định xem yêu cầu có được uỷ quyền hay không.
Làm việc với mã thông báo mã nhận dạng Firebase
Bạn có thể lấy mã thông báo mã Firebase theo 2 cách:
- Tạo mã thông báo mã Firebase bằng cách sử dụng API REST xác thực Firebase.
- Truy xuất mã thông báo mã nhận dạng Firebase của người dùng từ SDK xác thực Firebase.
Bằng cách truy xuất mã nhận dạng Firebase của người dùng, bạn có thể gửi yêu cầu thay mặt cho người dùng đó.
Đối với các yêu cầu được xác thực bằng mã thông báo giá trị nhận dạng Firebase và các yêu cầu chưa được xác thực, Cloud Firestore sẽ sử dụng Quy tắc bảo mật của Cloud Firestore để xác định xem một yêu cầu có được uỷ quyền hay không.
Làm việc với mã thông báo Google Identity OAuth 2.0
Bạn có thể tạo mã truy cập bằng cách dùng tài khoản dịch vụ với Thư viện ứng dụng API của Google hoặc làm theo các bước trong bài viết Sử dụng OAuth 2.0 cho ứng dụng từ máy chủ đến máy chủ. Bạn cũng có thể tạo mã thông báo bằng công cụ dòng lệnh gcloud
và lệnh gcloud auth application-default print-access-token
.
Mã thông báo này phải có phạm vi như sau để gửi yêu cầu đến API REST của Cloud Firestore:
https://www.googleapis.com/auth/datastore
Nếu bạn xác thực yêu cầu bằng tài khoản dịch vụ và mã thông báo OAuth 2.0 của Google Identity, Cloud Firestore sẽ giả định rằng các yêu cầu của bạn hành động thay mặt cho ứng dụng thay vì một người dùng cá nhân. Cloud Firestore cho phép các yêu cầu này bỏ qua các quy tắc bảo mật của bạn. Thay vào đó, Cloud Firestore sử dụng IAM để xác định xem một yêu cầu có được uỷ quyền hay không.
Bạn có thể kiểm soát quyền truy cập của tài khoản dịch vụ bằng cách chỉ định vai trò IAM của Cloud Firestore.
Xác thực bằng mã truy cập
Sau khi bạn lấy mã thông báo mã nhận dạng Firebase hoặc mã thông báo OAuth 2.0 của Google Identity, hãy truyền mã đó đến các điểm cuối của Cloud Firestore dưới dạng tiêu đề Authorization
được đặt thành Bearer {YOUR_TOKEN}
.
Thực hiện cuộc gọi REST
Tất cả điểm cuối của API REST đều tồn tại trong URL cơ sở https://firestore.googleapis.com/v1/
.
Để tạo đường dẫn đến một tài liệu có mã LA
trong bộ sưu tập cities
trong dự án YOUR_PROJECT_ID
, bạn sẽ sử dụng cấu trúc sau.
/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
Để tương tác với đường dẫn này, hãy kết hợp đường dẫn này với URL API cơ sở.
https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
Cách tốt nhất để bắt đầu thử nghiệm với API REST là sử dụng API Explorer. Trình khám phá này sẽ tự động tạo mã thông báo OAuth 2.0 của Google Identity và cho phép bạn kiểm tra API.
Phương thức
Dưới đây là nội dung mô tả ngắn gọn về 2 nhóm phương thức quan trọng nhất. Để biết danh sách đầy đủ, hãy xem tài liệu tham khảo API REST hoặc sử dụng API Explorer.
v1.projects.databases.documents
Thực hiện các thao tác CRUD trên tài liệu, tương tự như các thao tác được nêu trong hướng dẫn thêm dữ liệu hoặc lấy dữ liệu.
v1.projects.databases.collectionGroups.indexes
Thực hiện các thao tác trên chỉ mục như tạo chỉ mục mới, tắt một chỉ mục hiện có hoặc liệt kê tất cả chỉ mục hiện tại. Hữu ích cho việc tự động hoá việc di chuyển cấu trúc dữ liệu hoặc đồng bộ hoá chỉ mục giữa các dự án.
Ngoài ra, cho phép truy xuất siêu dữ liệu tài liệu, chẳng hạn như danh sách tất cả các trường và bộ sưu tập con của một tài liệu nhất định.
Mã lỗi
Khi một yêu cầu Cloud Firestore thành công, Cloud Firestore API sẽ trả về một mã trạng thái HTTP 200 OK
và dữ liệu được yêu cầu. Khi một yêu cầu không thành công, Cloud Firestore API sẽ trả về một mã trạng thái HTTP 4xx
hoặc 5xx
và một phản hồi có thông tin về lỗi.
Bảng sau đây liệt kê các hành động được đề xuất cho từng mã lỗi. Các mã này áp dụng cho các API REST và RPC của Cloud Firestore. Các SDK và thư viện ứng dụng trên Cloud Firestore có thể không trả về cùng một mã lỗi này.
Mã lỗi chuẩn | Mô tả | Việc nên làm |
---|---|---|
ABORTED |
Yêu cầu này đã xung đột với một yêu cầu khác. | Đối với cam kết phi giao dịch: Hãy thử lại yêu cầu hoặc sắp xếp lại mô hình dữ liệu của bạn để giảm tình trạng tranh chấp. Đối với các yêu cầu trong một giao dịch: Thử lại toàn bộ giao dịch hoặc tái cấu trúc mô hình dữ liệu để giảm tranh chấp. |
ALREADY_EXISTS |
Yêu cầu đã cố tạo một tài liệu đã tồn tại. | Đừng thử lại mà không khắc phục vấn đề. |
DEADLINE_EXCEEDED |
Máy chủ Cloud Firestore xử lý yêu cầu này đã vượt quá thời hạn. | Hãy thử lại bằng cách sử dụng thuật toán thời gian đợi luỹ thừa. |
FAILED_PRECONDITION |
Yêu cầu không đáp ứng được một trong các điều kiện tiên quyết. Ví dụ: yêu cầu truy vấn có thể đòi hỏi một chỉ mục chưa được xác định. Hãy xem trường thông báo trong phản hồi lỗi để biết điều kiện tiên quyết không thành công. | Đừng thử lại mà không khắc phục vấn đề. |
INTERNAL |
Máy chủ Cloud Firestore trả về một lỗi. | Đừng thử gửi lại yêu cầu này nhiều lần. |
INVALID_ARGUMENT |
Thông số yêu cầu chứa giá trị không hợp lệ. Hãy xem trường thông báo trong phản hồi lỗi để biết giá trị không hợp lệ. | Đừng thử lại mà không khắc phục vấn đề. |
NOT_FOUND |
Yêu cầu đã cố cập nhật một tài liệu không tồn tại. | Đừng thử lại mà không khắc phục vấn đề. |
PERMISSION_DENIED |
Người dùng không được phép thực hiện yêu cầu này. | Đừng thử lại mà không khắc phục vấn đề. |
RESOURCE_EXHAUSTED |
Dự án đã vượt quá hạn mức hoặc dung lượng của nhiều khu vực/nhiều khu vực. | Xác minh rằng bạn không vượt quá hạn mức dự án. Nếu bạn đã vượt quá hạn mức của dự án, đừng thử lại mà không khắc phục vấn đề. Nếu không, hãy thử lại bằng thuật toán thời gian đợi luỹ thừa. |
UNAUTHENTICATED |
Yêu cầu không bao gồm thông tin xác thực hợp lệ. | Đừng thử lại mà không khắc phục vấn đề. |
UNAVAILABLE |
Máy chủ Cloud Firestore trả về một lỗi. | Hãy thử lại bằng cách sử dụng thuật toán thời gian đợi luỹ thừa. |