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