যদিও Cloud Firestore ব্যবহারের সবচেয়ে সহজ উপায় হলো এর নেটিভ ক্লায়েন্ট লাইব্রেরিগুলোর একটি ব্যবহার করা, কিছু পরিস্থিতিতে সরাসরি REST API কল করা সুবিধাজনক হতে পারে।
REST API নিম্নলিখিত ব্যবহারের ক্ষেত্রগুলিতে সহায়ক হতে পারে:
- ইন্টারনেট অফ থিংস (IoT) ডিভাইসের মতো সীমিত সম্পদযুক্ত পরিবেশ থেকে Cloud Firestore অ্যাক্সেস করা, যেখানে একটি সম্পূর্ণ ক্লায়েন্ট লাইব্রেরি চালানো সম্ভব নয়।
- ডাটাবেস প্রশাসন স্বয়ংক্রিয় করা অথবা ডাটাবেসের বিস্তারিত মেটাডেটা পুনরুদ্ধার করা।
আপনি যদি gRPC-সমর্থিত কোনো ভাষা ব্যবহার করেন, তাহলে REST API-এর পরিবর্তে RPC API ব্যবহার করার কথা বিবেচনা করতে পারেন।
প্রমাণীকরণ এবং অনুমোদন
প্রমাণীকরণের জন্য, Cloud Firestore REST API একটি Firebase Authentication আইডি টোকেন অথবা একটি গুগল আইডেন্টিটি OAuth 2.0 টোকেন গ্রহণ করে। আপনার প্রদান করা টোকেনটি আপনার অনুরোধের অনুমোদনকে প্রভাবিত করে:
আপনার অ্যাপ্লিকেশনের ব্যবহারকারীদের অনুরোধ প্রমাণীকরণের জন্য ফায়ারবেস আইডি টোকেন ব্যবহার করুন। এই অনুরোধগুলির ক্ষেত্রে, Cloud Firestore Cloud Firestore Security Rules ব্যবহার করে নির্ধারণ করে যে অনুরোধটি অনুমোদিত কিনা।
আপনার অ্যাপ্লিকেশন থেকে আসা অনুরোধ, যেমন ডাটাবেস অ্যাডমিনিস্ট্রেশনের অনুরোধ, প্রমাণীকরণের জন্য একটি Google Identity OAuth 2.0 টোকেন এবং একটি সার্ভিস অ্যাকাউন্ট ব্যবহার করুন। এই ধরনের অনুরোধের ক্ষেত্রে, Cloud Firestore অনুরোধটি অনুমোদিত কিনা তা নির্ধারণ করতে Identity and Access Management (IAM) ব্যবহার করে।
ফায়ারবেস আইডি টোকেন নিয়ে কাজ করা
আপনি দুটি উপায়ে একটি ফায়ারবেস আইডি টোকেন পেতে পারেন:
- Firebase Authentication REST API ব্যবহার করে একটি Firebase ID টোকেন তৈরি করুন ।
- Firebase Authentication SDK থেকে একজন ব্যবহারকারীর Firebase ID টোকেন পুনরুদ্ধার করুন ।
কোনো ব্যবহারকারীর ফায়ারবেস আইডি টোকেন পুনরুদ্ধার করে, আপনি সেই ব্যবহারকারীর পক্ষ থেকে অনুরোধ পাঠাতে পারেন।
Firebase ID টোকেন দ্বারা প্রমাণীকৃত অনুরোধ এবং অপ্রমাণীকৃত অনুরোধ উভয়ের ক্ষেত্রেই, কোনো অনুরোধ অনুমোদিত কিনা তা নির্ধারণ করতে Cloud Firestore আপনার Cloud Firestore Security Rules ব্যবহার করে।
গুগল আইডেন্টিটি OAuth 2.0 টোকেন নিয়ে কাজ করা
আপনি গুগল এপিআই ক্লায়েন্ট লাইব্রেরির সাথে একটি সার্ভিস অ্যাকাউন্ট ব্যবহার করে অথবা "সার্ভার টু সার্ভার অ্যাপ্লিকেশনের জন্য OAuth 2.0 ব্যবহার" শীর্ষক ধাপগুলো অনুসরণ করে একটি অ্যাক্সেস টোকেন তৈরি করতে পারেন। এছাড়াও আপনি gcloud কমান্ড-লাইন টুল এবং gcloud auth application-default print-access-token কমান্ডটি ব্যবহার করে একটি টোকেন তৈরি করতে পারেন।
Cloud Firestore REST API-তে অনুরোধ পাঠানোর জন্য এই টোকেনটিতে নিম্নলিখিত স্কোপ থাকতে হবে:
-
https://www.googleapis.com/auth/datastore
আপনি যদি একটি সার্ভিস অ্যাকাউন্ট এবং একটি গুগল আইডেন্টিটি OAuth 2.0 টোকেন দিয়ে আপনার অনুরোধগুলি প্রমাণীকরণ করেন, তাহলে Cloud Firestore ধরে নেয় যে আপনার অনুরোধগুলি কোনো একক ব্যবহারকারীর পরিবর্তে আপনার অ্যাপ্লিকেশনের পক্ষ থেকে করা হচ্ছে। Cloud Firestore এই অনুরোধগুলিকে আপনার নিরাপত্তা নিয়ম উপেক্ষা করার অনুমতি দেয়। এর পরিবর্তে, কোনো অনুরোধ অনুমোদিত কিনা তা নির্ধারণ করতে Cloud Firestore IAM ব্যবহার করে।
আপনি Cloud Firestore আইএএম রোল নির্ধারণ করার মাধ্যমে সার্ভিস অ্যাকাউন্টগুলোর অ্যাক্সেস অনুমতি নিয়ন্ত্রণ করতে পারেন।
অ্যাক্সেস টোকেন দিয়ে প্রমাণীকরণ
আপনি একটি Firebase ID টোকেন অথবা একটি Google Identity OAuth 2.0 টোকেন পাওয়ার পর, সেটিকে Bearer {YOUR_TOKEN} হিসেবে সেট করা একটি Authorization হেডার হিসেবে Cloud Firestore এন্ডপয়েন্টগুলিতে পাঠান।
REST কল করা
সমস্ত REST API এন্ডপয়েন্ট https://firestore.googleapis.com/v1/ এই বেস URL-এর অধীনে বিদ্যমান।
YOUR_PROJECT_ID প্রোজেক্টের অধীনে cities কালেকশনে LA আইডিযুক্ত কোনো ডকুমেন্টের পাথ তৈরি করতে, আপনাকে নিম্নলিখিত কাঠামোটি ব্যবহার করতে হবে।
/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
এই পাথটি ব্যবহার করতে, এটিকে বেস API URL-এর সাথে যুক্ত করুন।
https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
REST API নিয়ে পরীক্ষা-নিরীক্ষা শুরু করার সেরা উপায় হলো API Explorer ব্যবহার করা, যা স্বয়ংক্রিয়ভাবে Google Identity OAuth 2.0 টোকেন তৈরি করে এবং আপনাকে API-টি পরীক্ষা করার সুযোগ দেয়।
পদ্ধতি
নিম্নে দুটি সবচেয়ে গুরুত্বপূর্ণ মেথড গ্রুপের সংক্ষিপ্ত বিবরণ দেওয়া হলো। সম্পূর্ণ তালিকার জন্য, REST API রেফারেন্স দেখুন অথবা API এক্সপ্লোরার ব্যবহার করুন।
v1.projects.databases.documents
ডকুমেন্টগুলোর উপর CRUD অপারেশন সম্পাদন করুন, যা 'অ্যাড ডেটা' বা 'গেট ডেটা' গাইডে বর্ণিত পদ্ধতির অনুরূপ।
v1.projects.databases.collectionGroups.indexes
ইনডেক্সের উপর বিভিন্ন কাজ সম্পাদন করুন, যেমন নতুন ইনডেক্স তৈরি করা, বিদ্যমান ইনডেক্স নিষ্ক্রিয় করা, বা সমস্ত বর্তমান ইনডেক্সের তালিকা দেখা। ডেটা স্ট্রাকচার মাইগ্রেশন স্বয়ংক্রিয় করতে বা বিভিন্ন প্রজেক্টের মধ্যে ইনডেক্স সিঙ্ক্রোনাইজ করতে এটি উপযোগী।
এছাড়াও এটি ডকুমেন্টের মেটাডেটা পুনরুদ্ধার করতে সক্ষম করে, যেমন কোনো নির্দিষ্ট ডকুমেন্টের সমস্ত ফিল্ড এবং সাব-কালেকশনের তালিকা।
ত্রুটি কোড
যখন একটি Cloud Firestore অনুরোধ সফল হয়, তখন Cloud Firestore এপিআই একটি HTTP 200 OK স্ট্যাটাস কোড এবং অনুরোধ করা ডেটা ফেরত দেয়। যখন কোনো অনুরোধ ব্যর্থ হয়, তখন Cloud Firestore এপিআই একটি HTTP 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 সার্ভার একটি ত্রুটি দেখিয়েছে। | এক্সপোনেনশিয়াল ব্যাকঅফ ব্যবহার করে পুনরায় চেষ্টা করুন। |