Cloud Firestore को इस्तेमाल करने का सबसे आसान तरीका, किसी एक स्थानीय क्लाइंट लाइब्रेरी का इस्तेमाल करना है. हालांकि, कुछ मामलों में REST API को सीधे कॉल करना ज़रूरी होता है.
REST API, इन कामों में मददगार हो सकता है:
- Cloud Firestore को सीमित संसाधनों वाले एनवायरमेंट से ऐक्सेस करना, जैसे कि इंटरनेट ऑफ़ थिंग्स (IoT) डिवाइस, जहां एक पूरी क्लाइंट लाइब्रेरी चलाई नहीं जा सकती.
- डेटाबेस को अपने-आप व्यवस्थित करना या पूरा डेटाबेस मेटाडेटा हासिल करना.
अगर gRPC के साथ काम करने वाली भाषा का इस्तेमाल किया जा रहा है, तो REST API के बजाय RPC API का इस्तेमाल करें.
पुष्टि करना और अनुमति देना
पुष्टि करने के लिए, Cloud Firestore REST API Firebase से पुष्टि करने आईडी टोकन या Google Identity OAuth 2.0 टोकन को स्वीकार करता है. आपके दिए गए टोकन से, आपके अनुरोध की अनुमति पर असर पड़ता है:
अपने ऐप्लिकेशन के उपयोगकर्ताओं के अनुरोधों की पुष्टि करने के लिए, Firebase आईडी टोकन का इस्तेमाल करें. इन अनुरोधों के लिए, Cloud Firestore, Cloud Firestore के सुरक्षा नियमों का इस्तेमाल करके यह तय करता है कि अनुरोध को मंज़ूरी दी गई है या नहीं.
अपने ऐप्लिकेशन से मिले अनुरोधों की पुष्टि करने के लिए, Google Identity OAuth 2.0 टोकन और सेवा खाते का इस्तेमाल करें. जैसे, डेटाबेस को मैनेज करने के अनुरोध. इन अनुरोधों के लिए, Cloud Firestore Identity and Access Management (IAM) का इस्तेमाल करके यह तय करता है कि किसी अनुरोध को अनुमति दी गई है या नहीं.
Firebase आईडी टोकन के साथ काम करना
Firebase आईडी टोकन पाने के दो तरीके हैं:
- Firebase Authentication REST API का इस्तेमाल करके Firebase आईडी टोकन जनरेट करें.
- Firebase से पुष्टि करने वाले SDK टूल से उपयोगकर्ता का Firebase आईडी टोकन वापस पाएं.
किसी उपयोगकर्ता का Firebase आईडी टोकन वापस पाने के बाद, उपयोगकर्ता की ओर से अनुरोध किए जा सकते हैं.
Firebase आईडी टोकन से पुष्टि किए गए अनुरोधों और बिना पुष्टि वाले अनुरोधों के लिए, Cloud Firestore आपके Cloud Firestore के सुरक्षा नियमों का इस्तेमाल करके तय करता है कि अनुरोध को अनुमति मिली है या नहीं.
Google Identity OAuth 2.0 टोकन के साथ काम करना
Google API क्लाइंट लाइब्रेरी वाले किसी सेवा खाते का इस्तेमाल करके, ऐक्सेस टोकन जनरेट किया जा सकता है. इसके अलावा, सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करना सेक्शन में दिया गया तरीका अपनाकर भी ऐक्सेस टोकन जनरेट किया जा सकता है. gcloud
कमांड-लाइन टूल और कमांड gcloud auth application-default print-access-token
की मदद से भी टोकन जनरेट किया जा सकता है.
Cloud Firestore REST API को अनुरोध भेजने के लिए, इस टोकन में यह स्कोप होना ज़रूरी है:
https://www.googleapis.com/auth/datastore
अगर आपने सेवा खाते और Google Identity OAuth 2.0 टोकन की मदद से अपने अनुरोधों की पुष्टि की है, तो Cloud Firestore यह मानता है कि आपके अनुरोध किसी एक उपयोगकर्ता के बजाय, ऐप्लिकेशन की ओर से काम करते हैं. Cloud Firestore, इन अनुरोधों को सुरक्षा के नियमों को अनदेखा करने की अनुमति देता है. इसके बजाय, Cloud Firestore, IAM का इस्तेमाल करके यह तय करता है कि किसी अनुरोध को अनुमति दी गई है या नहीं.
Cloud Firestore आईएएम की भूमिकाएं असाइन करके, सेवा खातों के ऐक्सेस की अनुमतियों को कंट्रोल किया जा सकता है.
ऐक्सेस टोकन से पुष्टि करना
Firebase आईडी टोकन या Google Identity OAuth 2.0
टोकन पाने के बाद, उसे Cloud Firestore एंडपॉइंट को Authorization
हेडर के तौर पर Bearer {YOUR_TOKEN}
पर सेट करें.
REST कॉल करें
सभी REST API एंडपॉइंट, बेस यूआरएल https://firestore.googleapis.com/v1/
में मौजूद होते हैं.
प्रोजेक्ट YOUR_PROJECT_ID
के तहत, cities
कलेक्शन में LA
आईडी वाले दस्तावेज़ का पाथ बनाने के लिए, आपको नीचे दिए गए स्ट्रक्चर का इस्तेमाल करना होगा.
/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
इस पाथ के साथ इंटरैक्ट करने के लिए, इसे बेस एपीआई यूआरएल के साथ जोड़ें.
https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
REST API के साथ एक्सपेरिमेंट शुरू करने का सबसे अच्छा तरीका है कि एपीआई एक्सप्लोरर का इस्तेमाल किया जाए. यह अपने-आप Google Identity OAuth 2.0 टोकन जनरेट करता है और आपको एपीआई की जांच करने की सुविधा देता है.
तरीके
यहां दो सबसे अहम तरीकों के ग्रुप के बारे में कम शब्दों में जानकारी दी गई है. पूरी सूची के लिए, REST API का रेफ़रंस देखें या एपीआई एक्सप्लोरर का इस्तेमाल करें.
v1.projects.databases.documents
डेटा जोड़ने या डेटा पाने से जुड़ी गाइड में बताए गए तरीके की तरह ही, दस्तावेज़ों पर CRUD से जुड़ी कार्रवाइयां करें.
v1.projects.databases.collectionGroups.indexes
इंडेक्स से जुड़ी कार्रवाइयां करें, जैसे कि नए इंडेक्स बनाना, किसी मौजूदा इंडेक्स को बंद करना या सभी मौजूदा इंडेक्स की सूची बनाना. डेटा स्ट्रक्चर को अपने-आप माइग्रेट करने या प्रोजेक्ट के बीच इंडेक्स सिंक करने में मदद करता है.
साथ ही, दिए गए दस्तावेज़ के सभी फ़ील्ड और सब-कलेक्शन की सूची जैसा दस्तावेज़ का मेटाडेटा वापस पाने की सुविधा चालू करता है.
गड़बड़ी कोड
Cloud Firestore अनुरोध पूरा होने पर, Cloud Firestore API, एचटीटीपी 200 OK
स्टेटस कोड और अनुरोध किया गया डेटा दिखाता है. अनुरोध फ़ेल होने पर, Cloud Firestore एपीआई, एचटीटीपी 4xx
या 5xx
स्टेटस कोड और गड़बड़ी की जानकारी के साथ रिस्पॉन्स दिखाता है.
यहां दी गई टेबल में, गड़बड़ी के हर कोड के लिए सुझाई गई कार्रवाइयों की सूची दी गई है. ये कोड, Cloud Firestore REST और RPC एपीआई पर लागू होते हैं. मुमकिन है कि Cloud Firestore के SDK टूल और क्लाइंट लाइब्रेरी ये गड़बड़ी वाले ये कोड न दिखाएं.
कैननिकल गड़बड़ी कोड | जानकारी | सुझाई गई कार्रवाई |
---|---|---|
ABORTED |
यह अनुरोध, किसी दूसरे अनुरोध से मेल नहीं खा रहा है. | लेन-देन से जुड़ी जवाबदेही के लिए: अनुरोध को फिर से करने की कोशिश करें या विवाद को कम करने के लिए, अपना डेटा मॉडल फिर से तैयार करें. लेन-देन के अनुरोधों के लिए: लेन-देन के दौरान फिर से अनुरोध करें या विवाद कम करने के लिए, अपने डेटा मॉडल को फिर से तैयार करें. |
ALREADY_EXISTS |
अनुरोध ने ऐसा दस्तावेज़ बनाने की कोशिश की है जो पहले से मौजूद है. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
DEADLINE_EXCEEDED |
अनुरोध को हैंडल करने वाला Cloud Firestore सर्वर, समयसीमा पार कर चुका है. | एक्सपोनेन्शियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें. |
FAILED_PRECONDITION |
अनुरोध, पहले से तय की गई एक शर्त के मुताबिक नहीं है. उदाहरण के लिए, क्वेरी करने के लिए किसी ऐसे इंडेक्स की ज़रूरत हो सकती है जिसे अब तक तय न किया गया हो. पहले से तय की गई शर्त के लिए गड़बड़ी के जवाब में मैसेज फ़ील्ड देखें. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
INTERNAL |
Cloud Firestore सर्वर में कोई गड़बड़ी मिली. | इस अनुरोध को एक से ज़्यादा बार न करें. |
INVALID_ARGUMENT |
अनुरोध पैरामीटर में एक अमान्य मान शामिल है. गड़बड़ी के रिस्पॉन्स में अमान्य वैल्यू के लिए मैसेज फ़ील्ड देखें. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
NOT_FOUND |
अनुरोध में ऐसे दस्तावेज़ को अपडेट करने की कोशिश की गई है जो मौजूद नहीं है. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
PERMISSION_DENIED |
उपयोगकर्ता के पास यह अनुरोध करने की अनुमति नहीं है. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
RESOURCE_EXHAUSTED |
इस प्रोजेक्ट ने अपने कोटे या इलाके/कई इलाकों के लिए तय सीमा पार कर ली है. | यह पुष्टि करें कि आपने प्रोजेक्ट के लिए तय किया गया कोटा पार नहीं किया है. अगर आपने प्रोजेक्ट कोटा पार कर लिया है, तो समस्या को ठीक किए बिना दोबारा कोशिश न करें. इसके अलावा, एक्सपोनेन्शियल बैकऑफ़ के साथ फिर से कोशिश करें. |
UNAUTHENTICATED |
अनुरोध में पुष्टि करने के लिए मान्य क्रेडेंशियल शामिल नहीं थे. | समस्या को ठीक किए बिना फिर से कोशिश न करें. |
UNAVAILABLE |
Cloud Firestore सर्वर में कोई गड़बड़ी मिली. | एक्सपोनेन्शियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें. |