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 Identity and Access Management (IAM) का इस्तेमाल करके यह तय करता है कि अनुरोध को अनुमति दी गई है या नहीं.

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

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 API पर लागू होते हैं. ऐसा हो सकता है कि 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 सर्वर ने गड़बड़ी का मैसेज दिया. एक्सपोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें.