Cloud Firestore का इस्तेमाल करने का सबसे आसान तरीका, नेटिव क्लाइंट लाइब्रेरी में से किसी एक का इस्तेमाल करना है. हालांकि, कुछ स्थितियों में REST API को सीधे तौर पर कॉल करना काम का हो सकता है.
REST API, इन मामलों में मददगार हो सकता है:
- संसाधन से जुड़ी पाबंदियों वाले एनवायरमेंट से Cloud Firestore को ऐक्सेस करना. जैसे, इंटरनेट ऑफ़ थिंग्स (IoT) डिवाइस. ऐसे डिवाइस पर पूरी क्लाइंट लाइब्रेरी को नहीं चलाया जा सकता.
- डेटाबेस एडमिनिस्ट्रेशन को ऑटोमेट करना या डेटाबेस का ज़्यादा जानकारी वाला मेटाडेटा वापस पाना.
अगर gRPC के साथ काम करने वाली किसी भाषा का इस्तेमाल किया जा रहा है, तो REST API के बजाय RPC API का इस्तेमाल करें.
पुष्टि करना और अनुमति देना
पुष्टि करने के लिए, Cloud Firestore REST API, या तो Firebase Authentication आईडी टोकन या Google Identity OAuth 2.0 टोकन को स्वीकार करता है. आपके दिए गए टोकन से, आपके अनुरोध की अनुमति पर असर पड़ता है:
अपने ऐप्लिकेशन के उपयोगकर्ताओं से मिले अनुरोधों की पुष्टि करने के लिए, Firebase आईडी टोकन का इस्तेमाल करें. इन अनुरोधों के लिए, Cloud Firestore uses Cloud Firestore Security Rules यह तय करने के लिए कि किसी अनुरोध को अनुमति मिली है या नहीं.
अपने ऐप्लिकेशन से मिले अनुरोधों की पुष्टि करने के लिए, Google Identity OAuth 2.0 टोकन और सेवा खाते का इस्तेमाल करें. जैसे, डेटाबेस एडमिनिस्ट्रेशन के अनुरोध. इन अनुरोधों के लिए, Cloud Firestore इस्तेमाल करता है पहचान और ऐक्सेस मैनेजमेंट (आईएएम) यह तय करने के लिए कि किसी अनुरोध को अनुमति मिली है या नहीं.
Firebase आईडी टोकन का इस्तेमाल करना
Firebase आईडी टोकन को दो तरीकों से हासिल किया जा सकता है:
- Firebase ID टोकन जनरेट करने के लिए Firebase Authentication REST API का इस्तेमाल करना.
- उपयोगकर्ता का Firebase आईडी टोकन, Firebase Authentication SDK से वापस पाना.
उपयोगकर्ता का Firebase आईडी टोकन वापस पाकर, उपयोगकर्ता की ओर से अनुरोध किए जा सकते हैं.
Firebase आईडी टोकन से पुष्टि किए गए अनुरोधों और बिना पुष्टि किए गए अनुरोधों के लिए, Cloud Firestore आपकी Cloud Firestore Security Rules का इस्तेमाल करके यह तय करता है कि किसी अनुरोध को अनुमति मिली है या नहीं.
Google Identity OAuth 2.0 टोकन का इस्तेमाल करना
Google API क्लाइंट लाइब्रेरी के साथ सेवा खाते का इस्तेमाल करके या सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करना में दिए गए चरणों को पूरा करके, ऐक्सेस टोकन जनरेट किया जा सकता है. कमांड-लाइन टूल और
कमांड gcloud auth application-default print-access-token का इस्तेमाल करके भी टोकन जनरेट किया जा सकता है.gcloud
REST API को अनुरोध भेजने के लिए, इस टोकन में यह दायरा होना चाहिए:Cloud Firestore
https://www.googleapis.com/auth/datastore
अगर सेवा खाते और Google Identity OAuth 2.0 टोकन से अपने अनुरोधों की पुष्टि की जाती है, तो Cloud Firestore यह मान लेता है कि आपके अनुरोध, किसी व्यक्ति के उपयोगकर्ता के बजाय आपके ऐप्लिकेशन की ओर से किए गए हैं. Cloud Firestore अनुमति देता है इन अनुरोधों को सुरक्षा से जुड़े आपके नियमों को अनदेखा करने की. इसके बजाय, Cloud Firestore यह तय करने के लिए आईएएम का इस्तेमाल करता है कि किसी अनुरोध को अनुमति मिली है या नहीं.
Cloud Firestore के आईएएम रोल असाइन करके, सेवा खातों की ऐक्सेस अनुमतियों को कंट्रोल किया जा सकता है.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 के साथ प्रयोग करने का सबसे अच्छा तरीका है कि API Explorer का इस्तेमाल किया जाए. यह Google Identity OAuth 2.0 टोकन अपने-आप जनरेट करता है और आपको एपीआई की जांच करने की अनुमति देता है.
तरीके
यहां, दो सबसे अहम तरीके के ग्रुप के बारे में संक्षेप में बताया गया है. पूरी सूची देखने के लिए, REST API का रेफ़रंस देखें या API Explorer का इस्तेमाल करें.
v1.projects.databases.documents
दस्तावेज़ों पर सी आर यू डी कार्रवाइयां करें. ये कार्रवाइयां, डेटा जोड़ना या डेटा पाना गाइड में बताई गई कार्रवाइयों जैसी होती हैं.
v1.projects.databases.collectionGroups.indexes
इंडेक्स पर कार्रवाइयां करें. जैसे, नए इंडेक्स बनाना, मौजूदा इंडेक्स को बंद करना या मौजूदा सभी इंडेक्स की सूची बनाना. डेटा स्ट्रक्चर माइग्रेशन को ऑटोमेट करने या प्रोजेक्ट के बीच इंडेक्स को सिंक करने के लिए काम का है.
इससे, दस्तावेज़ का मेटाडेटा भी वापस पाया जा सकता है. जैसे, किसी दस्तावेज़ के सभी फ़ील्ड और सब कलेक्शन की सूची.
गड़बड़ी का कोड
जब कोई Cloud Firestore अनुरोध पूरा होता है, तो
Cloud Firestore एपीआई, एचटीटीपी 200 OK स्टेटस कोड और
अनुरोध किया गया डेटा दिखाता है. कोई अनुरोध पूरा न होने पर, Cloud Firestore API,
एचटीटीपी 4xx या 5xx स्टेटस कोड और गड़बड़ी की जानकारी वाला जवाब दिखाता है.
यहां दिए गए टेबल में, हर गड़बड़ी कोड के लिए सुझाई गई कार्रवाइयों की सूची दी गई है. ये कोड, Cloud Firestore REST और RPC API पर लागू होते हैं. Cloud Firestore के 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 सर्वर ने गड़बड़ी दिखाई. | एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करके, फिर से कोशिश करें. |