الاتصال بقواعد بيانات مُدارة بالكامل من تشغيل السحابة

1. نظرة عامة

في هذا التمرين العملي، ستدمج قواعد بيانات بلا خادم(Spanner وFirestore) مع تطبيقات(Go وNode.js) تعمل في Cloud Run. يتضمّن تطبيق Cymbal Eats خدمات متعدّدة تعمل على Cloud Run. في الخطوات التالية، ستضبط الخدمات لاستخدام قاعدة البيانات الارتباطية Cloud Spanner وCloud Firestore، وهي قاعدة بيانات مستنِدة إلى تنسيق NoSQL. يتيح لك استخدام منتجات الحوسبة بدون خادم لمستوى البيانات ووقت تشغيل التطبيق تجريد جميع عمليات إدارة البنية الأساسية، والتركيز على إنشاء تطبيقك بدلاً من القلق بشأن النفقات العامة.

2. ما ستتعلمه

في هذه الميزة الاختبارية، ستتعرّف على كيفية تنفيذ ما يلي:

دمج Spanner
تفعيل "الخدمات المُدارة في Spanner"
دمجها في الرمز البرمجي
نشر الرمز البرمجي الذي يتصل بـ Spanner
دمج Firestore
تفعيل "الخدمات المُدارة" في Firestore
دمجها في الرمز البرمجي
نشر الرمز البرمجي الذي يتصل بخدمة Firestore

3- الإعداد والمتطلبات

إعداد البيئة بوتيرة ذاتية

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

إعداد البيئة

إنشاء متغيّر رقم تعريف المشروع

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export SPANNER_INSTANCE=inventory-instance
export SPANNER_DB=inventory-db
export REGION=us-east1
export SPANNER_CONNECTION_STRING=projects/$PROJECT_ID/instances/$SPANNER_INSTANCE/databases/$SPANNER_DB

تفعيل واجهات برمجة التطبيقات Spanner وCloud Run وCloud Build وArtifact Registry

gcloud services enable \
     compute.googleapis.com \
     spanner.googleapis.com \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     artifactregistry.googleapis.com \
     firestore.googleapis.com \
     appengine.googleapis.com \
     artifactregistry.googleapis.com

إنشاء نسخة طبق الأصل من المستودع

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git

الانتقال إلى الدليل

cd cymbal-eats/inventory-service/spanner

4. إنشاء مثيل Spanner وإعداده

‫Spanner هي قاعدة بيانات ارتباطية في الخلفية لخدمات المستودع. ستنشئ مثيلاً وقاعدة بيانات ومخططًا في Spanner في الخطوات التالية.

إنشاء نسخة افتراضية

إنشاء مثيل Cloud Spanner

gcloud spanner instances create $SPANNER_INSTANCE --config=regional-${REGION} \
--description="Cymbal Menu Inventory" --nodes=1

مثال على الناتج

Creating instance...done.

التحقّق مما إذا تم إعداد مثيل Spanner بشكلٍ صحيح

gcloud spanner instances list

مثال على الناتج

NAME: inventory-instance
DISPLAY_NAME: Cymbal Menu Inventory
CONFIG: regional-us-east1
NODE_COUNT: 1
PROCESSING_UNITS: 100
STATE: READY

إنشاء قاعدة بيانات ومخطط

أنشئ قاعدة بيانات جديدة واستخدِم لغة تعريف البيانات (DDL) في SQL العادي من Google لإنشاء مخطط قاعدة البيانات.

إنشاء ملف DDL

echo "CREATE TABLE InventoryHistory (ItemRowID STRING (36) NOT NULL, ItemID INT64 NOT NULL, InventoryChange INT64, Timestamp TIMESTAMP) PRIMARY KEY(ItemRowID)" >> table.ddl

إنشاء قاعدة بيانات Spanner

gcloud spanner databases create $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--ddl-file=table.ddl

مثال على الناتج

Creating database...done.

التحقّق من حالة قاعدة البيانات ومخططها

عرض حالة قاعدة البيانات

gcloud spanner databases describe $SPANNER_DB \
--instance=$SPANNER_INSTANCE

مثال على الناتج

createTime: '2022-04-22T15:11:33.559300Z'
databaseDialect: GOOGLE_STANDARD_SQL
earliestVersionTime: '2022-04-22T15:11:33.559300Z'
encryptionInfo:
- encryptionType: GOOGLE_DEFAULT_ENCRYPTION
name: projects/cymbal-eats-7-348013/instances/menu-inventory/databases/menu-inventory
state: READY
versionRetentionPeriod: 1h

عرض مخطط قاعدة البيانات

gcloud spanner databases ddl describe $SPANNER_DB \
--instance=$SPANNER_INSTANCE

مثال على الناتج

CREATE TABLE InventoryHistory (
  ItemRowID STRING(36) NOT NULL,
  ItemID INT64 NOT NULL,
  InventoryChange INT64,
  TimeStamp TIMESTAMP,
) PRIMARY KEY(ItemRowID);

5- دمج Spanner

في هذا القسم، ستتعرّف على كيفية دمج Spanner في تطبيقك. بالإضافة إلى ذلك، يوفّر SQL Spanner مكتبات برامج و برامج تشغيل JDBC و برامج تشغيل R2DBC و واجهات REST API و واجهات RPC API، ما يتيح لك دمج Spanner في أي تطبيق.

في القسم التالي، ستستخدم مكتبة برامج Go لتثبيت البيانات ومصادقتها وتعديلها في Spanner.

تثبيت مكتبة البرامج

تسهّل مكتبة برامج Cloud Spanner عملية الدمج مع Cloud Spanner من خلال استخدام "بيانات الاعتماد التلقائية للتطبيق" (ADC) تلقائيًا للعثور على بيانات اعتماد حساب الخدمة.

إعداد المصادقة

ترصد واجهة سطر الأوامر في Google Cloud ومكتبات برامج Google Cloud تلقائيًا متى يتم تشغيلها على Google Cloud، وتستخدم حساب خدمة وقت التشغيل لإصدار Cloud Run الحالي. تُعرف هذه الاستراتيجية باسم "بيانات الاعتماد التلقائية للتطبيق"، وهي تتيح إمكانية نقل الرمز البرمجي بين بيئات متعددة.

ومع ذلك، من الأفضل إنشاء هوية مخصّصة من خلال منحها حساب خدمة يديره المستخدم بدلاً من حساب الخدمة التلقائي.

منح دور "مشرف قاعدة بيانات Spanner" لحساب الخدمة

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/spanner.databaseAdmin"

مثال على الناتج

Updated IAM policy for project [cymbal-eats-6422-3462].
[...]

استخدام مكتبات العملاء

تجرّد مكتبات برامج Spanner المعقّدة من عملية الدمج مع Spanner، وتتوفّر بلغات برمجة شائعة عديدة.

إنشاء عميل Spanner

برنامج Spanner هو برنامج قراءة وكتابة البيانات في قاعدة بيانات Cloud Spanner. يمكن استخدام العميل بشكل متزامن، باستثناء الطريقة Close.

ينشئ المقتطف أدناه عميل Spanner

main.go

var dataClient *spanner.Client
...
dataClient, err = spanner.NewClient(ctx, databaseName)

يمكنك اعتبار "العميل" بمثابة اتصال بقاعدة بيانات: يجب أن تمرّ جميع تفاعلاتك مع Cloud Spanner من خلال "العميل". عادةً ما يتم إنشاء Client عند بدء تشغيل تطبيقك، ثم إعادة استخدام هذا Client للقراءة والكتابة وتنفيذ المعاملات. يستخدم كل عميل موارد في Cloud Spanner.

تعديل البيانات

تتوفّر طرق متعددة لإدراج البيانات وتعديلها وحذفها من قاعدة بيانات Spanner. في ما يلي الطرق المتاحة.

في هذا التمرين العملي، ستستخدم عمليات التغيير لتعديل البيانات في Spanner.

التغييرات في Spanner

التعديل هو حاوية لعمليات التعديل. تمثّل عملية التغيير تسلسلاً من عمليات الإدراج والتعديل والحذف التي يطبّقها Cloud Spanner بشكل ذري على صفوف وجداول مختلفة في قاعدة بيانات Cloud Spanner.

main.go

m := []*spanner.Mutation{}

m = append(m, spanner.Insert(
        "inventoryHistory",
         inventoryHistoryColumns,
        []interface{}{uuid.New().String(), element.ItemID, element.InventoryChange, time.Now()}))

يُدرِج مقتطف الرمز صفًا جديدًا في جدول سجلّ المستودع.

النشر والاختبار

بعد إعداد Spanner ومراجعة عناصر الرمز الرئيسية، يمكنك نشر التطبيق على Cloud Run.

نشر التطبيق على Cloud Run

يمكن لخدمة Cloud Run إنشاء الرمز البرمجي ونقله ونشره تلقائيًا باستخدام أمر واحد. في الأمر التالي، ستستدعي الأمر deploy على خدمة run، مع تمرير المتغيرات التي يستخدمها التطبيق قيد التشغيل، مثل SPANNER_CONNECTION_STRING الذي أنشأته سابقًا.

انقر على "فتح الوحدة الطرفية"
نشر خدمة المستودع إلى Cloud Run

gcloud run deploy inventory-service \
    --source . \
    --region $REGION \
    --update-env-vars SPANNER_CONNECTION_STRING=$SPANNER_CONNECTION_STRING \
    --allow-unauthenticated \
    --project=$PROJECT_ID \
    --quiet

مثال على الناتج

Service [inventory-service] revision [inventory-service-00001-sug] has been deployed and is serving 100 percent of traffic.
Service URL: https://inventory-service-ilwytgcbca-uk.a.run.app

تخزين عنوان URL للخدمة

INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
  --platform managed \
  --region $REGION \
  --format=json | jq \
  --raw-output ".status.url")

اختبار تطبيق Cloud Run

إدراج عنصر

في Cloudshell، أدخِل الأمر التالي.

POST_URL=$INVENTORY_SERVICE_URL/updateInventoryItem
curl -i -X POST ${POST_URL} \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "itemID": 1,
        "inventoryChange": 5
    }
]'

مثال على الناتج

HTTP/2 200
access-control-allow-origin: *
content-type: application/json
x-cloud-trace-context: 10c32f0863d26521497dc26e86419f13;o=1
date: Fri, 22 Apr 2022 21:41:38 GMT
server: Google Frontend
content-length: 2

OK

طلب معلومات عن منتج

طلب بيانات من خدمة المستودع

GET_URL=$INVENTORY_SERVICE_URL/getAvailableInventory
curl -i ${GET_URL}

مثال على إجابة

HTTP/2 200
access-control-allow-origin: *
content-type: text/plain; charset=utf-8
x-cloud-trace-context: b94f921e4c2ae90210472c88eb05ace8;o=1
date: Fri, 22 Apr 2022 21:45:50 GMT
server: Google Frontend
content-length: 166

[{"ItemID":1,"Inventory":5}]

6. مفاهيم Spanner

تستعلم Cloud Spanner عن قواعد البيانات باستخدام عبارات SQL التعريفية. توضّح عبارات SQL ما يريده المستخدم بدون وصف كيفية الحصول على النتائج.

في الوحدة الطرفية، أدخِل هذا الأمر للاستعلام عن الجدول بحثًا عن السجلّ الذي تم إنشاؤه سابقًا.

gcloud spanner databases execute-sql $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--sql='SELECT * FROM InventoryHistory WHERE ItemID=1'

مثال على الناتج

ItemRowID: 1
ItemID: 1
InventoryChange: 3
Timestamp:

خطط تنفيذ طلبات البحث

خطة تنفيذ طلب البحث هي سلسلة من الخطوات التي يستخدمها Spanner للحصول على النتائج. قد تتوفّر عدة طرق للحصول على نتائج عبارة SQL معيّنة. يمكن الوصول إلى خطط تنفيذ طلبات البحث في وحدة التحكّم ومكتبات البرامج. للاطّلاع على طريقة تعامل Spanner مع طلبات بحث SQL، اتّبِع الخطوات التالية:

في وحدة التحكّم، افتح صفحة مثيلات Cloud Spanner.
الانتقال إلى مثيلات Cloud Spanner
انقر على اسم مثيل Cloud Spanner. من قسم قواعد البيانات، اختَر قاعدة البيانات التي تريد تنفيذ طلب بحث فيها.
انقر على "طلب البحث".
أدخِل طلب البحث التالي في محرّر طلب البحث

SELECT * FROM InventoryHistory WHERE ItemID=1

انقر على "تشغيل".
انقر على "التفسير"

تعرض Cloud Console خطة تنفيذ مرئية لطلب البحث.

أداة تحسين طلبات البحث

يقارن محسِّن طلبات البحث في Cloud Spanner بين خطط التنفيذ البديلة ويختار الخطة الأكثر فعالية. بمرور الوقت، سيتطوّر محسِّن طلبات البحث، ما يؤدي إلى توسيع الخيارات في خطة تنفيذ طلب البحث وتحسين دقة التقديرات التي تستند إليها هذه الخيارات، ما يؤدي إلى خطط تنفيذ طلبات بحث أكثر كفاءة.

تطرح Cloud Spanner تحديثات المحسِّن كإصدارات جديدة من محسِّن الاستعلام. بشكلٍ تلقائي، تبدأ كل قاعدة بيانات في استخدام أحدث إصدار من أداة التحسين بعد 30 يومًا على الأقل من طرح هذا الإصدار.

لمعرفة الإصدار المستخدَم عند تنفيذ طلب بحث في gcloud spanner، اضبط العلامة ‎–query-mode على PROFILE.

أدخِل الأمر التالي لعرض إصدار أداة التحسين

gcloud spanner databases execute-sql $SPANNER_DB --instance=$SPANNER_INSTANCE \
--query-mode=PROFILE --sql='SELECT * FROM InventoryHistory'

مثال على الناتج

TOTAL_ELAPSED_TIME: 6.18 msecs
CPU_TIME: 5.17 msecs
ROWS_RETURNED: 1
ROWS_SCANNED: 1
OPTIMIZER_VERSION: 3
 RELATIONAL Distributed Union
 (1 execution, 0.11 msecs total latency)
 subquery_cluster_node: 1
    |
    +- RELATIONAL Distributed Union
    |  (1 execution, 0.09 msecs total latency)
    |  call_type: Local, subquery_cluster_node: 2
    |   |
    |   \- RELATIONAL Serialize Result
    |      (1 execution, 0.08 msecs total latency)
    |       |
    |       +- RELATIONAL Scan
    |       |  (1 execution, 0.08 msecs total latency)
    |       |  Full scan: true, scan_target: InventoryHistory, scan_type: TableScan
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  ItemRowID
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  ItemID
    |       |   |
    |       |   +- SCALAR Reference
    |       |   |  InventoryChange
    |       |   |
    |       |   \- SCALAR Reference
    |       |      Timestamp
    |       |
    |       +- SCALAR Reference
    |       |  $ItemRowID
    |       |
    |       +- SCALAR Reference
    |       |  $ItemID
    |       |
    |       +- SCALAR Reference
    |       |  $InventoryChange
    |       |
    |       \- SCALAR Reference
    |          $Timestamp
    |
    \- SCALAR Constant
       true

ItemRowID: 1
ItemID: 1
InventoryChange: 3
Timestamp:

تحديث إصدار أداة التحسين

أحدث إصدار في وقت إعداد هذا الدرس التطبيقي هو الإصدار 4. بعد ذلك، ستعدّل جدول Spanner لاستخدام الإصدار 4 من أداة تحسين طلبات البحث.

تعديل أداة التحسين

gcloud spanner databases ddl update $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--ddl='ALTER DATABASE InventoryHistory
SET OPTIONS (optimizer_version = 4)'

مثال على الناتج

Schema updating...done.

أدخِل الأمر التالي لعرض تحديث إصدار أداة التحسين

gcloud spanner databases execute-sql $SPANNER_DB --instance=$SPANNER_INSTANCE \
--query-mode=PROFILE --sql='SELECT * FROM InventoryHistory'

مثال على الناتج

TOTAL_ELAPSED_TIME: 8.57 msecs
CPU_TIME: 8.54 msecs
ROWS_RETURNED: 1
ROWS_SCANNED: 1
OPTIMIZER_VERSION: 4
[...]

عرض إصدار "محسِّن طلبات البحث" في "أداة استكشاف المقاييس"

يمكنك استخدام "مستكشف المقاييس" في Cloud Console لعرض عدد طلبات البحث لمثيل قاعدة البيانات. يمكنك الاطّلاع على إصدار أداة التحسين المستخدَم في كل قاعدة بيانات.

انتقِل إلى "المراقبة" في Cloud Console، ثم اختَر مستكشف المقاييس في القائمة اليمنى.
في الحقل نوع المورد، اختَر "مثيل Cloud Spanner".
في حقل المقياس، اختَر "عدد طلبات البحث" و"تطبيق".
في حقل التجميع حسب، اختَر قاعدة البيانات وoptimizer_version والحالة.

7. إنشاء قاعدة بيانات Firestore وإعدادها

‫Firestore هي قاعدة بيانات مستنِدة إلى تنسيق NoSQL ومصمَّمة للتوسّع التلقائي والأداء العالي وسهولة تطوير التطبيقات. على الرغم من أنّ واجهة Firestore تتضمّن العديد من الميزات نفسها المتوفّرة في قواعد البيانات التقليدية، تختلف قاعدة بيانات NoSQL عنها في وصف العلاقات بين عناصر البيانات.

ستساعدك المهمة التالية في إنشاء تطبيق خدمة طلبات Cloud Run يستند إلى Firestore. ستستدعي خدمة الطلبات خدمة المستودع التي تم إنشاؤها في القسم السابق للاستعلام عن قاعدة بيانات Spanner قبل بدء الطلب. ستضمن هذه الخدمة توفّر مخزون كافٍ وإمكانية تنفيذ الطلب.

8. مفاهيم Firestore

نموذج البيانات

تتكوّن قاعدة بيانات Firestore من مجموعات ومستندات.

المستندات

يحتوي كل مستند على مجموعة من أزواج المفاتيح والقيم. تم تحسين Firestore لتخزين مجموعات كبيرة من المستندات الصغيرة.

المجموعات

يجب تخزين جميع المستندات في مجموعات. يمكن أن تحتوي المستندات على مجموعات فرعية وعناصر متداخلة، بما في ذلك الحقول الأساسية مثل السلاسل أو العناصر المعقّدة مثل القوائم.

إنشاء قاعدة بيانات Firestore

إنشاء قاعدة بيانات Firestore

gcloud firestore databases create --location=$REGION

مثال على الناتج

Success! Selected Google Cloud Firestore Native database for cymbal-eats-6422-3462

9- دمج Firestore في تطبيقك

في هذا القسم، ستعدّل حساب الخدمة وتضيف حسابات خدمة الوصول إلى Firestore وتراجع قواعد الأمان في Firestore وتنفّذها وتراجع طريقة تعديل البيانات في Firestore.

إعداد المصادقة

منح دور مستخدم Datastore لحساب الخدمة

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/datastore.user"

مثال على الناتج

Updated IAM policy for project [cymbal-eats-6422-3462].

قواعد الأمان في Firestore

توفّر قواعد الأمان إمكانية التحكّم في الوصول إلى البيانات والتحقّق من صحتها بتنسيق واضح وسهل الاستخدام.

انتقِل إلى دليل order-service/starter-code

cd ~/cymbal-eats/order-service

افتح ملف firestore.rules في محرّر السحابة الإلكترونية

cat firestore.rules

firestore.rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents { ⇐ All database
    match /{document=**} { ⇐ All documents
      allow read: if true; ⇐ Allow reads
    }
    match /{document=**} {
      allow write: if false; ⇐ Deny writes
    }
  }
}

تحذير: من أفضل الممارسات الحدّ من الوصول إلى مساحة تخزين Firestore. لأغراض هذا الدرس التطبيقي، يُسمح بجميع عمليات القراءة. هذا ليس إعدادًا مناسبًا للإنتاج.

تفعيل "الخدمات المُدارة" في Firestore

انقر على "فتح الوحدة الطرفية"
أنشئ ملف ‎ .firebaserc باستخدام رقم تعريف المشروع الحالي. يتم تخزين إعدادات أهداف النشر في ملف ‎ .firebaserc في دليل مشروعك.

firebaserc.tmpl

sed "s/PROJECT_ID/$PROJECT_ID/g" firebaserc.tmpl > .firebaserc

تنزيل ملف Firebase الثنائي

curl -sL https://firebase.tools | upgrade=true bash

مثال على الناتج

-- Checking for existing firebase-tools on PATH...
Your machine already has firebase-tools@10.7.0 installed. Nothing to do.
-- All done!

نشر قواعد Firestore

firebase deploy

مثال على الناتج

=== Deploying to 'cymbal-eats-6422-3462'...

i  deploying firestore
i  cloud.firestore: checking firestore.rules for compilation errors...
✔  cloud.firestore: rules file firestore.rules compiled successfully
i  firestore: uploading rules firestore.rules...
✔  firestore: released rules firestore.rules to cloud.firestore

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/cymbal-eats-6422-3462/overview

تعديل البيانات

يتم إنشاء المجموعات والمستندات ضِمنيًا في Firestore. ما عليك سوى تعيين البيانات لمستند ضمن مجموعة. إذا لم تكن المجموعة أو المستند متوفّرَين، ينشئ Firestore المجموعة أو المستند.

إضافة بيانات إلى Firestore

هناك عدة طرق لكتابة البيانات في Cloud Firestore:

اضبط بيانات مستند ضمن مجموعة، مع تحديد معرّف المستند بشكلٍ صريح.
أضِف مستندًا جديدًا إلى مجموعة. في هذه الحالة، تنشئ Cloud Firestore تلقائيًا معرّف المستند.
إنشاء مستند فارغ باستخدام معرّف يتم إنشاؤه تلقائيًا، وتعيين البيانات إليه لاحقًا

سيرشدك القسم التالي إلى كيفية إنشاء مستند باستخدام طريقة set.

ضبط مستند

استخدِم طريقة set() لإنشاء مستند. باستخدام الطريقة set()، يجب تحديد معرّف للمستند الذي تريد إنشاءه.

ألقِ نظرة على مقتطف الرمز البرمجي أدناه.

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.set({
    orderNumber: 123,
    name: Anne,
    address: 555 Bright Street,
    city: Mountain View,
    state: CA,
    zip: 94043,
    orderItems: [id: 1],
    status: 'New'
  });

ستنشئ هذه التعليمة البرمجية مستندًا يحدّد رقم تعريف مستند من إنشاء المستخدم 123. لأن تنشئ Firestore رقم تعريف نيابةً عنك، استخدِم الطريقتَين add() أو create().

تعديل مستند

تتيح لك طريقة التعديل update()تعديل بعض حقول المستند بدون الكتابة فوق المستند بأكمله.

في المقتطف أدناه، يعدّل الرمز الطلب 123

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.update(name: "Anna");

حذف مستند

في Firestore، يمكنك حذف المجموعات أو المستندات أو الحقول المحدّدة من المستند. لحذف مستند، استخدِم الطريقة delete().

يؤدي المقتطف أدناه إلى حذف الطلب 123.

index.js

const orderDoc = db.doc(`orders/123`);
await orderDoc.delete();

10. النشر والاختبار

في هذا القسم، ستنفّذ التطبيق على Cloud Run وتختبر طرق الإنشاء والتعديل والحذف.

نشر التطبيق على Cloud Run

تخزين عنوان URL في المتغير INVENTORY_SERVICE_URL للدمج مع "خدمة المستودع"

INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
 --region=$REGION \
 --format=json | jq \
 --raw-output ".status.url")

نشر خدمة الطلبات

gcloud run deploy order-service \
  --source . \
  --platform managed \
  --region $REGION \
  --allow-unauthenticated \
  --project=$PROJECT_ID \
  --set-env-vars=INVENTORY_SERVICE_URL=$INVENTORY_SERVICE_URL \
  --quiet

مثال على الناتج

[...]
Done.
Service [order-service] revision [order-service-00001-qot] has been deployed and is serving 100 percent of traffic.
Service URL: https://order-service-3jbm3exegq-uk.a.run.app

اختبار تطبيق Cloud Run

إنشاء مستند

تخزين عنوان URL لتطبيق خدمة الطلبات في متغيّر للاختبار

ORDER_SERVICE_URL=$(gcloud run services describe order-service \
  --platform managed \
  --region $REGION \
  --format=json | jq \
  --raw-output ".status.url")

إنشاء طلب شراء ونشر طلب جديد في قاعدة بيانات Firestore

curl --request POST $ORDER_SERVICE_URL/order \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Jane Doe",
         "email": "Jane.Doe-cymbaleats@gmail.com",
    "address": "123 Maple",
    "city": "Buffalo",
    "state": "NY",
    "zip": "12346",
    "orderItems": [
        {
            "id": 1
        }
    ]
}'

مثال على الناتج

{"orderNumber":46429}

احفظ رقم الطلب لاستخدامه لاحقًا

export ORDER_NUMBER=<value_from_output>

عرض النتائج

عرض النتائج في Firestore

انتقِل إلى وحدة تحكّم Firestore.
انقر على "البيانات".

تعديل مستند

لم يتضمّن الطلب الذي تم إرساله الكمية.

تعديل السجلّ وإضافة زوج المفتاح/القيمة الخاص بالكمية

curl --location -g --request PATCH $ORDER_SERVICE_URL/order/${ORDER_NUMBER} \
--header 'Content-Type: application/json' \
--data-raw '{
"orderItems": [
        {   
            "id": 1,
            "quantity": 1   
        }
    ]
}'

مثال على الناتج

{"status":"success"}

عرض النتائج

عرض النتائج في Firestore

انتقِل إلى وحدة تحكّم Firestore.
انقر على "البيانات".

حذف مستند

حذف العنصر 46429 من مجموعة الطلبات في Firestore

curl --location -g --request DELETE $ORDER_SERVICE_URL/order/${ORDER_NUMBER}

عرض النتائج

انتقِل إلى وحدة تحكّم Firestore.
انقر على "البيانات".

11. تهانينا!

تهانينا، لقد أكملت الدرس التطبيقي.

الخطوة التالية:

استكشِف دروسًا تطبيقية أخرى حول Cymbal Eats:

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، احذف المشروع الذي يحتوي على الموارد أو احتفظ بالمشروع واحذف الموارد الفردية.

حذف المشروع

أسهل طريقة لإيقاف الفوترة هي حذف المشروع الذي أنشأته لتنفيذ البرنامج التعليمي.