تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. نظرة عامة

سوف تدمج في هذا التمرين المعملي قواعد بيانات بدون خادم(Spanner وFirestore) مع تطبيقات(Go وNode.js) تعمل في نظام التشغيل Cloud. يشتمل تطبيق 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 وواجهات برمجة تطبيقات RPC، ما يتيح لك دمج Spanner في أي تطبيق.

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

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

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

ضبط إعدادات المصادقة

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

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

منح دور مشرف قاعدة بيانات 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. الجهاز العميل آمن للاستخدام بالتزامن، باستثناء طريقة "إغلاق".

ينشئ المقتطف أدناه عميل مفتاح ربط.

main.go

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

يمكنك اعتبار العميل اتصال قاعدة بيانات: يجب أن تمر جميع تفاعلاتك مع Cloud Spanner عبر عميل. عادةً ما تقوم بإنشاء عميل عند بدء تشغيل التطبيق، ثم إعادة استخدام هذا العميل لقراءة المعاملات وكتابتها وتنفيذها. يستخدم كل عميل الموارد في 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 الذي أنشأته سابقًا.

انقر فوق "Open Terminal" (فتح المحطة الطرفية)
نشر خدمة المستودع في 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. من قسم قواعد البيانات، حدد قاعدة البيانات التي تريد الاستعلام عنها.
انقر فوق "Query" (استعلام).
أدخِل الاستعلام التالي في محرر طلبات البحث

SELECT * FROM InventoryHistory WHERE ItemID=1

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

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

مُحسِّن طلبات البحث

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

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

للاطلاع على الإصدار المستخدم عند تشغيل طلب بحث في أداة ربط gcloud، عيِّن علامة –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
[...]

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

يمكنك استخدام Metrics Explorer (مستكشف المقاييس) في Cloud Console لعرض عدد طلبات البحث لمثيل قاعدة البيانات. يمكنك معرفة إصدار المحسِّن الذي يتم استخدامه في كل قاعدة بيانات.

انتقِل إلى أداة "المراقبة" في Cloud Console واختَر مستكشف المقاييس في القائمة اليمنى.
في الحقل نوع المورد، اختَر "مثيل Cloud Spanner".
في الحقل المقياس، اختَر "عدد طلبات البحث" ثم "تطبيق".
في الحقل التجميع حسب، اختَر قاعدة البيانات ومُحسِّن_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.

ضبط إعدادات المصادقة

منح دور مستخدم "مخزن البيانات" لحساب الخدمة

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 المُدارة

انقر فوق "Open Terminal" (فتح المحطة الطرفية)
أنشئ ملف .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

تخزين عنوان URL في المتغير INVENTORY_SERVICE_URL لدمجه مع Inventory Service

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 مقابل الموارد المُستخدَمة في هذا الدليل التوجيهي، يمكنك إما حذف المشروع الذي يحتوي على الموارد أو الاحتفاظ بالمشروع وحذف الموارد الفردية.

حذف المشروع

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