Cloud Firestore REST API का उपयोग करें

जबकि क्लाउड फायरस्टोर का उपयोग करने का सबसे आसान तरीका मूल क्लाइंट लाइब्रेरीज़ में से एक का उपयोग करना है, कुछ स्थितियाँ हैं जब सीधे REST API को कॉल करना उपयोगी होता है।

REST API निम्नलिखित उपयोग मामलों के लिए सहायक हो सकता है:

• संसाधन-बाधित वातावरण, जैसे इंटरनेट ऑफ थिंग्स (IoT) डिवाइस से क्लाउड फायरस्टोर तक पहुंच, जहां संपूर्ण क्लाइंट लाइब्रेरी चलाना संभव नहीं है।
• डेटाबेस प्रशासन को स्वचालित करना या विस्तृत डेटाबेस मेटाडेटा पुनर्प्राप्त करना।

यदि आप gRPC-समर्थित भाषा का उपयोग कर रहे हैं, तो REST API के बजाय RPC API का उपयोग करने पर विचार करें।

सत्यापन और प्राधिकरण

प्रमाणीकरण के लिए, क्लाउड फायरस्टोर REST API या तो फायरबेस प्रमाणीकरण आईडी टोकन या Google आइडेंटिटी OAuth 2.0 टोकन स्वीकार करता है। आपके द्वारा प्रदान किया गया टोकन आपके अनुरोध के प्राधिकरण को प्रभावित करता है:

• अपने एप्लिकेशन के उपयोगकर्ताओं के अनुरोधों को प्रमाणित करने के लिए फायरबेस आईडी टोकन का उपयोग करें। इन अनुरोधों के लिए, क्लाउड फायरस्टोर यह निर्धारित करने के लिए क्लाउड फायरस्टोर सुरक्षा नियमों का उपयोग करता है कि कोई अनुरोध अधिकृत है या नहीं।

• अपने एप्लिकेशन से अनुरोधों को प्रमाणित करने के लिए Google पहचान OAuth 2.0 टोकन और एक सेवा खाते का उपयोग करें, जैसे डेटाबेस प्रशासन के लिए अनुरोध। इन अनुरोधों के लिए, क्लाउड फायरस्टोर यह निर्धारित करने के लिए पहचान और पहुंच प्रबंधन (IAM) का उपयोग करता है कि कोई अनुरोध अधिकृत है या नहीं।

फायरबेस आईडी टोकन के साथ कार्य करना

आप दो तरीकों से फायरबेस आईडी टोकन प्राप्त कर सकते हैं:

• फ़ायरबेस प्रमाणीकरण REST API का उपयोग करके फ़ायरबेस आईडी टोकन जेनरेट करें ।
• फ़ायरबेस प्रमाणीकरण एसडीके से उपयोगकर्ता का फ़ायरबेस आईडी टोकन पुनर्प्राप्त करें ।

उपयोगकर्ता का फायरबेस आईडी टोकन पुनर्प्राप्त करके, आप उपयोगकर्ता की ओर से अनुरोध कर सकते हैं।

फायरबेस आईडी टोकन के साथ प्रमाणित अनुरोधों के लिए और अप्रमाणित अनुरोधों के लिए, क्लाउड फायरस्टोर आपके क्लाउड फायरस्टोर सुरक्षा नियमों का उपयोग यह निर्धारित करने के लिए करता है कि कोई अनुरोध अधिकृत है या नहीं।

Google Identity OAuth 2.0 टोकन के साथ कार्य करना

आप Google API क्लाइंट लाइब्रेरी के साथ एक सेवा खाते का उपयोग करके या सर्वर से सर्वर अनुप्रयोगों के लिए OAuth 2.0 का उपयोग करने के चरणों का पालन करके एक एक्सेस टोकन उत्पन्न कर सकते हैं। आप gcloud कमांड-लाइन टूल और gcloud auth application-default print-access-token कमांड के साथ एक टोकन भी उत्पन्न कर सकते हैं।

क्लाउड फायरस्टोर REST API को अनुरोध भेजने के लिए इस टोकन में निम्नलिखित गुंजाइश होनी चाहिए:

• https://www.googleapis.com/auth/datastore

यदि आप अपने अनुरोधों को एक सेवा खाते और Google पहचान OAuth 2.0 टोकन के साथ प्रमाणित करते हैं, तो क्लाउड फायरस्टोर मानता है कि आपके अनुरोध किसी व्यक्तिगत उपयोगकर्ता के बजाय आपके एप्लिकेशन की ओर से कार्य करते हैं। क्लाउड फायरस्टोर इन अनुरोधों को आपके सुरक्षा नियमों को अनदेखा करने की अनुमति देता है। इसके बजाय, क्लाउड फायरस्टोर यह निर्धारित करने के लिए IAM का उपयोग करता है कि कोई अनुरोध अधिकृत है या नहीं।

आप क्लाउड फायरस्टोर IAM भूमिकाएँ निर्दिष्ट करके सेवा खातों की पहुँच अनुमतियों को नियंत्रित कर सकते हैं।

एक्सेस टोकन के साथ प्रमाणीकरण

फायरबेस आईडी टोकन या Google आइडेंटिटी OAuth 2.0 टोकन प्राप्त करने के बाद, इसे Bearer {YOUR_TOKEN} पर सेट Authorization हेडर के रूप में क्लाउड फायरस्टोर एंडपॉइंट पर पास करें।

REST कॉल करना

सभी REST API एंडपॉइंट बेस URL 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 एक्सप्लोरर का उपयोग करना है, जो स्वचालित रूप से Google पहचान OAuth 2.0 टोकन उत्पन्न करता है और आपको API की जांच करने की अनुमति देता है।

तरीकों

नीचे दो सबसे महत्वपूर्ण विधि समूहों का संक्षिप्त विवरण दिया गया है। पूरी सूची के लिए, REST API संदर्भ देखें या API एक्सप्लोरर का उपयोग करें।

v1.projects.databases.documents

दस्तावेज़ों पर सीआरयूडी संचालन निष्पादित करें, जैसे कि डेटा जोड़ें या डेटा प्राप्त करें गाइड में उल्लिखित हैं।

v1.projects.databases.collectionGroups.indexes

इंडेक्स पर कार्य करें जैसे नए इंडेक्स बनाना, मौजूदा इंडेक्स को अक्षम करना, या सभी मौजूदा इंडेक्स को सूचीबद्ध करना। डेटा संरचना माइग्रेशन को स्वचालित करने या परियोजनाओं के बीच अनुक्रमणिका को सिंक्रनाइज़ करने के लिए उपयोगी।

दस्तावेज़ मेटाडेटा की पुनर्प्राप्ति को भी सक्षम बनाता है, जैसे किसी दिए गए दस्तावेज़ के लिए सभी फ़ील्ड और उपसंग्रहों की सूची।

त्रुटि कोड

जब क्लाउड फायरस्टोर अनुरोध सफल होता है, तो क्लाउड फायरस्टोर एपीआई एक HTTP 200 OK स्टेटस कोड और अनुरोधित डेटा लौटाता है। जब कोई अनुरोध विफल हो जाता है, तो क्लाउड फायरस्टोर एपीआई एक HTTP 4xx या 5xx स्थिति कोड और त्रुटि के बारे में जानकारी के साथ एक प्रतिक्रिया देता है।

निम्न तालिका प्रत्येक त्रुटि कोड के लिए अनुशंसित कार्रवाइयों को सूचीबद्ध करती है। ये कोड क्लाउड फायरस्टोर REST और RPC API पर लागू होते हैं। क्लाउड फायरस्टोर एसडीके और क्लाइंट लाइब्रेरी ये समान त्रुटि कोड वापस नहीं कर सकते हैं।

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