Cloud Firestore REST एपीआई का इस्तेमाल करें

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 आईडी टोकन हासिल करके, उसकी ओर से अनुरोध किए जा सकते हैं.

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 पर सेट किए गए Authorization हेडर के तौर पर पास करें.

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 का रेफ़रंस देखें या एपीआई एक्सप्लोरर का इस्तेमाल करें.

v1.projects.databases.documents

दस्तावेज़ों पर CRUD ऑपरेशन करें. ये ऑपरेशन, डेटा जोड़ना या डेटा पाना गाइड में बताए गए ऑपरेशन से मिलते-जुलते हैं.

v1.projects.databases.collectionGroups.indexes

इंडेक्स पर कार्रवाइयां करें. जैसे, नए इंडेक्स बनाना, किसी मौजूदा इंडेक्स को बंद करना या सभी मौजूदा इंडेक्स की सूची बनाना. डेटा स्ट्रक्चर के माइग्रेशन को ऑटोमेट करने या प्रोजेक्ट के बीच इंडेक्स सिंक करने के लिए मददगार.

इससे दस्तावेज़ का मेटाडेटा भी वापस पाया जा सकता है. जैसे, दिए गए दस्तावेज़ के सभी फ़ील्ड और सब-कलेक्शन की सूची.

गड़बड़ी के कोड

जब कोई Cloud Firestore अनुरोध पूरा हो जाता है, तो Cloud Firestore एपीआई, एचटीटीपी 200 OK स्टेटस कोड और अनुरोध किया गया डेटा दिखाता है. जब कोई अनुरोध पूरा नहीं होता है, तो Cloud Firestore एपीआई एचटीटीपी 4xx या 5xx स्टेटस कोड दिखाता है. साथ ही, गड़बड़ी के बारे में जानकारी देने वाला रिस्पॉन्स भी दिखाता है.

नीचे दी गई टेबल में, हर गड़बड़ी कोड के लिए सुझाई गई कार्रवाइयों की सूची दी गई है. ये कोड, Cloud Firestore REST और RPC API पर लागू होते हैं. ऐसा हो सकता है कि Cloud Firestore एसडीके और क्लाइंट लाइब्रेरी पर ये गड़बड़ी कोड न दिखें.

कैननिकल गड़बड़ी कोड ब्यौरा सुझाई गई कार्रवाई
ABORTED अनुरोध, किसी दूसरे अनुरोध से मेल नहीं खाता. बिना लेन-देन वाले कमिट के लिए:
अनुरोध को फिर से आज़माएं या विवाद को कम करने के लिए, अपने डेटा मॉडल का स्ट्रक्चर फिर से बनाएं.

लेन-देन के अनुरोधों के लिए:
पूरे लेन-देन को फिर से आज़माएं या विवाद को कम करने के लिए, अपने डेटा मॉडल का स्ट्रक्चर फिर से बनाएं.
ALREADY_EXISTS अनुरोध में ऐसा दस्तावेज़ बनाने की कोशिश की गई जो पहले से मौजूद है. समस्या ठीक किए बिना, फिर से कोशिश न करें.
DEADLINE_EXCEEDED अनुरोध को प्रोसेस करने वाले Cloud Firestore सर्वर ने समयसीमा खत्म होने के बाद भी अनुरोध को प्रोसेस नहीं किया. एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें.
FAILED_PRECONDITION अनुरोध, पहले से तय की गई एक शर्त के मुताबिक नहीं है. उदाहरण के लिए, क्वेरी के अनुरोध के लिए, किसी ऐसे इंडेक्स की ज़रूरत पड़ सकती है जिसे अभी तक तय नहीं किया गया है. पहले से तय की गई शर्त के लिए गड़बड़ी के मैसेज में मैसेज फ़ील्ड देखें. समस्या ठीक किए बिना, फिर से कोशिश न करें.
INTERNAL Cloud Firestore सर्वर ने गड़बड़ी का मैसेज दिया. इस अनुरोध को एक से ज़्यादा बार दोहराएं.
INVALID_ARGUMENT अनुरोध पैरामीटर में अमान्य वैल्यू शामिल है. गलत वैल्यू के लिए गड़बड़ी के रिस्पॉन्स में मैसेज फ़ील्ड देखें. समस्या ठीक किए बिना, फिर से कोशिश न करें.
NOT_FOUND अनुरोध में ऐसे दस्तावेज़ को अपडेट करने की कोशिश की गई है जो मौजूद नहीं है. समस्या को ठीक किए बिना फिर से कोशिश न करें.
PERMISSION_DENIED उपयोगकर्ता के पास यह अनुरोध करने की अनुमति नहीं है. समस्या को ठीक किए बिना फिर से कोशिश न करें.
RESOURCE_EXHAUSTED प्रोजेक्ट के लिए तय किया गया कोटा या क्षेत्र/एक से ज़्यादा क्षेत्रों के लिए तय की गई क्षमता पार हो गई है. पुष्टि करें कि आपने प्रोजेक्ट के लिए तय किया गया कोटा पार न किया हो. अगर आपने प्रोजेक्ट कोटा पार कर लिया है, तो समस्या को ठीक किए बिना दोबारा कोशिश न करें.

इसके अलावा, एक्सपोनेन्शियल बैकऑफ़ के साथ फिर से कोशिश करें.
UNAUTHENTICATED अनुरोध में पुष्टि करने के लिए मान्य क्रेडेंशियल शामिल नहीं थे. समस्या को ठीक किए बिना फिर से कोशिश न करें.
UNAVAILABLE Cloud Firestore सर्वर में कोई गड़बड़ी मिली. एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें.