Cloud Firestore का इस्तेमाल करने का सबसे आसान तरीका, नेटिव क्लाइंट लाइब्रेरी में से किसी एक का इस्तेमाल करना है. हालांकि, कुछ मामलों में सीधे तौर पर REST API को कॉल करना फ़ायदेमंद होता है.
REST API, इन मामलों में मददगार हो सकता है:
- संसाधन की कमी वाले एनवायरमेंट, जैसे कि इंटरनेट ऑफ़ थिंग्स (IoT) डिवाइस से Cloud Firestore को ऐक्सेस करना. ऐसे डिवाइस पर पूरी क्लाइंट लाइब्रेरी नहीं चलाई जा सकती.
- डेटाबेस एडमिनिस्ट्रेशन को अपने-आप होने वाली प्रोसेस बनाना या डेटाबेस के मेटाडेटा की ज़्यादा जानकारी पाना.
अगर 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 आईडी टोकन, Firebase Authentication SDK टूल से वापस पाएं.
किसी उपयोगकर्ता का 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 एक्सप्लोरर का इस्तेमाल करें.
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 एसडीके और क्लाइंट लाइब्रेरी, गड़बड़ी के ये कोड न दिखाएं.
| कैननिकल गड़बड़ी का कोड | ब्यौरा | सुझाई गई कार्रवाई |
|---|---|---|
ABORTED |
अनुरोध, किसी दूसरे अनुरोध से मेल नहीं खाता. | लेन-देन से जुड़े कमिट के लिए: अनुरोध को फिर से भेजें या डेटा मॉडल को फिर से स्ट्रक्चर करें, ताकि विवाद कम हो. लेन-देन में किए गए अनुरोधों के लिए: पूरे लेन-देन को फिर से करें या डेटा मॉडल को फिर से स्ट्रक्चर करें, ताकि विवाद कम हो. |
ALREADY_EXISTS |
अनुरोध में, ऐसा दस्तावेज़ बनाने की कोशिश की गई है जो पहले से मौजूद है. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
DEADLINE_EXCEEDED |
अनुरोध को मैनेज करने वाले Cloud Firestore सर्वर की समयसीमा खत्म हो गई है. | एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें. |
FAILED_PRECONDITION |
अनुरोध, पहले से तय की गई किसी एक शर्त को पूरा नहीं करता है. उदाहरण के लिए, किसी क्वेरी के अनुरोध के लिए ऐसे इंडेक्स की ज़रूरत पड़ सकती है जिसे अभी तक तय नहीं किया गया है. प्रीकंडिशन पूरी न होने पर, गड़बड़ी के जवाब में मौजूद मैसेज फ़ील्ड देखें. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
INTERNAL |
Cloud Firestore सर्वर में कोई गड़बड़ी हुई. | इस अनुरोध को एक से ज़्यादा बार न दोहराएं. |
INVALID_ARGUMENT |
अनुरोध पैरामीटर में अमान्य वैल्यू शामिल है. अमान्य वैल्यू के लिए, गड़बड़ी के जवाब में मौजूद मैसेज फ़ील्ड देखें. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
NOT_FOUND |
अनुरोध में, ऐसे दस्तावेज़ को अपडेट करने की कोशिश की गई है जो मौजूद नहीं है. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
PERMISSION_DENIED |
उपयोगकर्ता को यह अनुरोध करने की अनुमति नहीं है. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
RESOURCE_EXHAUSTED |
प्रोजेक्ट ने कोटा या क्षेत्र/एक से ज़्यादा क्षेत्रों के लिए तय की गई क्षमता को पार कर लिया है. | पुष्टि करें कि आपने प्रोजेक्ट के लिए तय किया गया कोटा पार न किया हो. अगर आपने किसी प्रोजेक्ट के लिए तय की गई सीमा पार कर ली है, तो समस्या को ठीक किए बिना फिर से कोशिश न करें. इसके अलावा, एक्सपोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें. |
UNAUTHENTICATED |
अनुरोध में पुष्टि करने के मान्य क्रेडेंशियल शामिल नहीं किए गए थे. | समस्या ठीक किए बिना, फिर से कोशिश न करें. |
UNAVAILABLE |
Cloud Firestore सर्वर में कोई गड़बड़ी हुई. | एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें. |