اتصال به پایگاه های داده کاملاً مدیریت شده از Cloud Run

1. بررسی اجمالی

در این آزمایشگاه، پایگاه داده های بدون سرور (Spanner و Firestore) را با برنامه های کاربردی (Go و Node.js) در حال اجرا در Cloud Run ادغام خواهید کرد. برنامه Cymbal Eats شامل چندین سرویس است که در Cloud Run اجرا می شوند. در مراحل زیر، سرویس‌ها را برای استفاده از پایگاه داده رابطه‌ای Cloud Spanner و Cloud Firestore ، یک پایگاه‌داده اسناد NoSQL پیکربندی می‌کنید. استفاده از محصولات بدون سرور برای ردیف داده و زمان اجرای برنامه به شما این امکان را می دهد که تمام مدیریت زیرساخت را از بین ببرید و به جای نگرانی در مورد هزینه های اضافی، بر ساخت برنامه خود تمرکز کنید.

2. آنچه یاد خواهید گرفت

در این آزمایشگاه با نحوه انجام کارهای زیر آشنا می شوید:

• ادغام آچار
• خدمات مدیریت آچار را فعال کنید
• ادغام در کد
• کد اتصال به Spanner را اجرا کنید
• Firestore را ادغام کنید
• سرویس های مدیریت شده Firestore را فعال کنید
• ادغام در کد
• کد اتصال به Firestore را مستقر کنید

3. راه اندازی و الزامات

تنظیم محیط خود به خود

1. به Google Cloud Console وارد شوید و یک پروژه جدید ایجاد کنید یا از یک موجود استفاده مجدد کنید. اگر قبلاً یک حساب Gmail یا Google Workspace ندارید، باید یک حساب ایجاد کنید .

• نام پروژه نام نمایشی برای شرکت کنندگان این پروژه است. این یک رشته کاراکتری است که توسط API های Google استفاده نمی شود. همیشه می توانید آن را به روز کنید.
• شناسه پروژه در تمام پروژه‌های Google Cloud منحصربه‌فرد است و تغییرناپذیر است (پس از تنظیم نمی‌توان آن را تغییر داد). Cloud Console به طور خودکار یک رشته منحصر به فرد تولید می کند. معمولاً برای شما مهم نیست که چیست. در اکثر کدها، باید شناسه پروژه خود را ارجاع دهید (معمولاً با نام PROJECT_ID شناخته می شود). اگر شناسه تولید شده را دوست ندارید، ممکن است یک شناسه تصادفی دیگر ایجاد کنید. از طرف دیگر، می‌توانید خودتان را امتحان کنید، و ببینید آیا در دسترس است یا خیر. پس از این مرحله نمی توان آن را تغییر داد و در طول مدت پروژه باقی می ماند.
• برای اطلاع شما، یک مقدار سوم وجود دارد، یک شماره پروژه ، که برخی از API ها از آن استفاده می کنند. در مورد هر سه این مقادیر در مستندات بیشتر بیاموزید.

احتیاط: شناسه پروژه در سطح جهانی منحصر به فرد است و پس از انتخاب شما توسط شخص دیگری نمی توان از آن استفاده کرد. شما تنها کاربر آن شناسه هستید. حتی اگر پروژه ای حذف شود، ID نمی تواند دوباره استفاده شود

توجه: اگر از یک حساب جیمیل استفاده می‌کنید، می‌توانید مکان پیش‌فرض را روی بدون سازمان بگذارید. اگر از حساب Google Workspace استفاده می کنید، مکانی را انتخاب کنید که برای سازمان شما منطقی باشد.

2. در مرحله بعد، برای استفاده از منابع Cloud/APIها باید صورتحساب را در کنسول Cloud فعال کنید . اجرا کردن از طریق این کد لبه هزینه زیادی نخواهد داشت. برای خاموش کردن منابع برای جلوگیری از تحمیل صورت‌حساب فراتر از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید حذف کنید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری هستند.

تنظیم محیط

1. یک متغیر ID پروژه ایجاد کنید

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

2. فعال کردن Spanner، Cloud Run، Cloud Build و Artifact Registry API

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

3. مخزن را شبیه سازی کنید

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

4. به دایرکتوری بروید

cd cymbal-eats/inventory-service/spanner

4. یک نمونه Spanner ایجاد و پیکربندی کنید

Spanner پایگاه داده رابطه ای باطن خدمات موجودی است. در مراحل زیر یک نمونه Spanner، پایگاه داده و طرحواره ایجاد خواهید کرد.

یک نمونه ایجاد کنید

1. یک نمونه Cloud Spanner ایجاد کنید

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

خروجی نمونه

Creating instance...done.   

2. بررسی کنید که آیا نمونه 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

یک پایگاه داده و طرحواره ایجاد کنید

یک پایگاه داده جدید ایجاد کنید و از زبان تعریف داده استاندارد SQL Google (DDL) برای ایجاد طرح پایگاه داده استفاده کنید.

1. یک فایل DDL ایجاد کنید

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

2. پایگاه داده Spanner را ایجاد کنید

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

خروجی نمونه

Creating database...done.

وضعیت پایگاه داده و طرحواره را تأیید کنید

1. مشاهده وضعیت پایگاه داده

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

توجه: وضعیت پایگاه داده به صورت READY نشان داده می شود

2. مشاهده طرح و نقشه پایگاه داده

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);

توجه: پایگاه داده دارای چهار ستون است. ItemRowID کلید اصلی است.

همچنین می‌توانید جزئیات را در کنسول نمای کلی آچار مشاهده کنید.

5. یکپارچه کردن آچار

در این بخش، نحوه ادغام Spanner را در برنامه خود خواهید آموخت. علاوه بر این، SQL Spanner کتابخانه های Client ، درایورهای JDBC ، درایورهای R2DBC ، REST API و RPC API را ارائه می دهد که به شما امکان می دهد Spanner را در هر برنامه ای ادغام کنید.

در بخش بعدی، از کتابخانه سرویس گیرنده Go برای نصب، احراز هویت و اصلاح داده ها در Spanner استفاده خواهید کرد.

نصب کتابخانه مشتری

کتابخانه سرویس گیرنده Cloud Spanner با استفاده خودکار از Application Default Credentials (ADC) برای یافتن اعتبار حساب سرویس شما، ادغام با Cloud Spanner را آسان‌تر می‌کند.

توجه: با به‌روزرسانی کد، کد شروع خطا خواهد داشت. می توانید این خطاها را نادیده بگیرید.

احراز هویت را تنظیم کنید

کتابخانه‌های سرویس گیرنده Google Cloud و Google Cloud به‌طور خودکار تشخیص می‌دهند که در Google Cloud در حال اجرا هستند و از حساب سرویس زمان اجرا نسخه فعلی Cloud Run استفاده می‌کنند. این استراتژی Application Default Credentials نامیده می شود و قابلیت حمل کد را در محیط های مختلف فعال می کند.

با این حال، بهتر است یک هویت اختصاصی با اختصاص یک حساب سرویس مدیریت شده توسط کاربر به جای حساب سرویس پیش فرض ایجاد کنید.

1. نقش مدیر پایگاه داده Spanner را به حساب سرویس اعطا کنید

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$[e-mail]" \
--role="roles/spanner.databaseAdmin"

خروجی نمونه

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

با نقش مدیر پایگاه داده Spanner، حساب سرویس می تواند:

• دریافت/لیست تمام نمونه های Cloud Spanner در پروژه.
• ایجاد / لیست / رها کردن پایگاه داده در یک نمونه.
• اعطا/لغو دسترسی به پایگاه های داده در پروژه.
• از همه پایگاه‌های داده Cloud Spanner در پروژه بخوانید و بنویسید.

استفاده از کتابخانه های مشتری

کتابخانه های کلاینت Spanner پیچیدگی های ادغام با Spanner را انتزاعی می کنند و در بسیاری از زبان های برنامه نویسی محبوب موجود هستند.

یک کلاینت Spanner ایجاد کنید

کلاینت Spanner یک کلاینت برای خواندن و نوشتن داده ها در پایگاه داده Cloud Spanner است. یک کلاینت برای استفاده همزمان امن است، به جز روش Close.

قطعه زیر یک کلاینت آچار ایجاد می کند

main.go

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

می توانید Client را به عنوان یک اتصال پایگاه داده در نظر بگیرید: تمام تعاملات شما با Cloud Spanner باید از طریق یک Client انجام شود. معمولاً هنگام راه‌اندازی برنامه، یک Client ایجاد می‌کنید و سپس از آن مشتری برای خواندن، نوشتن و اجرای تراکنش‌ها دوباره استفاده می‌کنید. هر مشتری از منابع موجود در Cloud Spanner استفاده می کند.

داده ها را اصلاح کنید

راه های مختلفی برای درج، به روز رسانی و حذف داده ها از پایگاه داده Spanner وجود دارد. در زیر روش های موجود فهرست شده است.

• Google Cloud Console
• gcloud CLI
• DML
• جهش ها

در این آزمایشگاه، از جهش ها برای تغییر داده ها در 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 را که قبلاً ایجاد کرده‌اید ارسال می‌کند.

1. روی Open Terminal کلیک کنید
2. سرویس موجودی را در 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

توجه: اگر از شما خواسته شد که ادامه دهید، Y را تایپ کنید

3. آدرس سرویس را ذخیره کنید

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

برنامه Cloud Run را تست کنید

درج یک مورد

1. در 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

یک مورد را پرس و جو کنید

1. خدمات موجودی را پرس و جو کنید

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. مفاهیم آچار

Cloud Spanner پایگاه داده خود را با استفاده از عبارات SQL اعلامی پرس و جو می کند. عبارات SQL نشان می دهد که کاربر چه می خواهد بدون اینکه توضیح دهد چگونه نتایج به دست می آید.

1. در ترمینال، این دستور را وارد کنید تا جدول مربوط به رکورد قبلی ایجاد شده را پرس و جو کنید.

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 را مدیریت می کند:

1. در کنسول، صفحه نمونه‌های Cloud Spanner را باز کنید.
2. به نمونه های Cloud Spanner بروید
3. روی نام نمونه Cloud Spanner کلیک کنید. از قسمت پایگاه داده، پایگاه داده ای را که می خواهید پرس و جو کنید انتخاب کنید.
4. روی Query کلیک کنید.
5. عبارت زیر را در ویرایشگر پرس و جو وارد کنید

SELECT * FROM InventoryHistory WHERE ItemID=1

6. روی RUN کلیک کنید
7. روی توضیح کلیک کنید

Cloud Console یک طرح اجرای بصری برای درخواست شما نمایش می دهد.

از نظر مفهومی، یک طرح اجرا درختی از عملگرهای رابطه ای است. هر عملگر سطرها را از ورودی(های) خود می خواند و سطرهای خروجی تولید می کند. ریشه اجرا به عنوان نتیجه پرس و جو SQL برگردانده می شود.

بهینه ساز پرس و جو

بهینه ساز پرس و جو Cloud Spanner برنامه های اجرای جایگزین را مقایسه می کند و کارآمدترین آنها را انتخاب می کند. با گذشت زمان، بهینه‌ساز پرس و جو تکامل می‌یابد و انتخاب‌ها را در طرح اجرای پرس‌و‌جو گسترش می‌دهد و دقت تخمین‌هایی را که به آن انتخاب‌ها اطلاع می‌دهند، بهبود می‌بخشد و منجر به طرح‌های اجرای پرس‌وجو کارآمدتر می‌شود.

Cloud Spanner به‌روزرسانی‌های بهینه‌ساز را به عنوان نسخه‌های جدید بهینه‌ساز پرس و جو ارائه می‌کند. به طور پیش فرض، هر پایگاه داده کمتر از 30 روز پس از انتشار آن نسخه، شروع به استفاده از آخرین نسخه بهینه ساز می کند.

برای مشاهده نسخه مورد استفاده هنگام اجرای یک پرس و جو در آچار gcloud، پرچم –query-mode را روی PROFILE تنظیم کنید.

1. برای مشاهده نسخه بهینه ساز دستور زیر را وارد کنید

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:

نسخه فعلی روی نسخه 3 تنظیم شده است. برای یافتن جدیدترین نسخه، تاریخچه نسخه را بررسی کنید

نسخه بهینه ساز را به روز کنید

جدیدترین نسخه در زمان این آزمایشگاه نسخه 4 است. در مرحله بعد، Spanner Table را برای استفاده از نسخه 4 برای بهینه ساز پرس و جو به روز می کنید.

2. بهینه ساز را به روز کنید

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

خروجی نمونه

Schema updating...done. 

3. برای مشاهده آپدیت نسخه بهینه ساز دستور زیر را وارد کنید

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
[...]

OPTIMIZER_VERSION به نسخه 4 به روز شده است

نسخه بهینه ساز پرس و جو را در Metrics Explorer تجسم کنید

می توانید از Metrics Explorer در Cloud Console برای تجسم تعداد پرس و جوها برای نمونه پایگاه داده خود استفاده کنید. می توانید ببینید که کدام نسخه بهینه ساز در هر پایگاه داده استفاده می شود.

1. به Monitoring در Cloud Console بروید و Metrics Explorer را در منوی سمت چپ انتخاب کنید.
2. در قسمت نوع منبع ، Cloud Spanner Instance را انتخاب کنید.
3. در قسمت Metric ، Count of query را انتخاب کرده و Apply را انتخاب کنید.
4. در قسمت Group By ، پایگاه داده، optimizer_version و status را انتخاب کنید.

7. ایجاد و پیکربندی پایگاه داده Firestore

Firestore یک پایگاه داده اسناد NoSQL است که برای مقیاس بندی خودکار، کارایی بالا و سهولت توسعه برنامه ساخته شده است. در حالی که رابط Firestore بسیاری از ویژگی های مشابه پایگاه داده های سنتی را دارد، یک پایگاه داده NoSQL در توصیف روابط بین اشیاء داده با آنها متفاوت است.

کار زیر شما را از طریق ایجاد یک سرویس سفارش برنامه کاربردی Cloud Run با پشتیبانی Firestore راهنمایی می کند. سرویس سفارش با سرویس موجودی ایجاد شده در بخش قبل تماس می گیرد تا قبل از شروع سفارش، پایگاه داده Spanner را پرس و جو کند. این سرویس اطمینان حاصل می کند که موجودی کافی وجود دارد و سفارش می تواند پر شود.

8. مفاهیم Firestore

مدل داده

پایگاه داده Firestore از مجموعه ها و اسناد تشکیل شده است.

اسناد

هر سند شامل مجموعه ای از جفت های کلید-مقدار است. Firestore برای ذخیره مجموعه های بزرگ اسناد کوچک بهینه شده است.

در مثال بالا، سند شناسه سفارش شامل چهار جفت کلید-مقدار است. کلید orderItems شامل آرایه ای از جفت های کلید-مقدار است.

مجموعه ها

شما باید تمام اسناد را در مجموعه ها ذخیره کنید. اسناد می‌توانند شامل مجموعه‌های فرعی و اشیاء تودرتو، از جمله فیلدهای ابتدایی مانند رشته‌ها یا اشیاء پیچیده مانند فهرست‌ها باشند.

سند شناسه سفارش در مجموعه سفارشات در مثال بالا ذخیره می شود.

یک پایگاه داده Firestore ایجاد کنید

1. پایگاه داده Firestore را ایجاد کنید

gcloud firestore databases create --location=$REGION

خروجی نمونه

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

پایگاه داده Firestore جدیدی که ایجاد کردید در حال حاضر خالی است. پایگاه داده جدید همچنین دارای مجموعه ای پیش فرض از قوانین امنیتی است که به هر کسی اجازه می دهد تا عملیات خواندن را انجام دهد و از نوشتن در پایگاه داده جلوگیری کند.

9. ادغام Firestore در برنامه شما

در این بخش، حساب سرویس را به‌روزرسانی می‌کنید، حساب‌های سرویس دسترسی Firestore را اضافه می‌کنید، قوانین امنیتی Firestore را بررسی و اجرا می‌کنید و نحوه تغییر داده‌ها در Firestore را بررسی می‌کنید.

احراز هویت را تنظیم کنید

1. نقش کاربر Datastore را به حساب سرویس اعطا کنید

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$[e-mail]" \
  --role="roles/datastore.user"

خروجی نمونه

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

نقش کاربر Datastore امکان دسترسی خواندن/نوشتن به داده ها در پایگاه داده Firestore را فراهم می کند.

قوانین امنیتی Firestore

قوانین امنیتی کنترل دسترسی و اعتبار سنجی داده ها را با فرمت واضح و در عین حال ساده ارائه می دهند.

1. به دایرکتوری order-service/ starter-code بروید

cd ~/cymbal-eats/order-service

2. فایل firestore.rules را در ویرایشگر ابری باز کنید

cat firestore.rules

firestore.قوانین

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.rules حاوی قوانینی است که به همه عملیات خواندن اجازه می دهد و تمام عملیات نوشتن را برای همه جداول در پایگاه داده Firestore رد می کند. برای کسب اطلاعات بیشتر در مورد قوانین فایر استور، شروع به کار با قوانین امنیتی را مرور کنید.

هشدار: بهترین روش محدود کردن دسترسی به فضای ذخیره سازی Firestore است. برای اهداف این آزمایشگاه، همه خواندن ها مجاز است. این یک پیکربندی تولید توصیه شده نیست.

سرویس های مدیریت شده Firestore را فعال کنید

1. روی Open Terminal کلیک کنید
2. فایل .firebaserc را با شناسه پروژه فعلی ایجاد کنید. تنظیمات برای استقرار اهداف در فایل .firebaserc در فهرست پروژه شما ذخیره می شود.

firebaserc.tmpl

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

2. باینری فایربیس را دانلود کنید

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!

3. قوانین 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

به‌روزرسانی‌های قوانین امنیتی Cloud Firestore می‌تواند تا یک دقیقه طول بکشد تا بر جستارها و شنوندگان جدید تأثیر بگذارد. با این حال، انتشار کامل تغییرات و تأثیر بر شنوندگان فعال ممکن است تا 10 دقیقه طول بکشد.

داده ها را اصلاح کنید

مجموعه ها و اسناد به طور ضمنی در Firestore ایجاد می شوند. به سادگی داده ها را به یک سند در یک مجموعه اختصاص دهید. اگر مجموعه یا سند وجود نداشته باشد، Firestor آن را ایجاد می کند.

افزودن داده به 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 یک ID از طرف شما ایجاد کند، از متد add() یا create() استفاده کنید.

هنگام استفاده از set() اگر سند وجود نداشته باشد، ایجاد می شود. اگر سند وجود داشته باشد، محتویات آن با داده های ارائه شده جدید رونویسی می شود.

یک اسناد را به روز کنید

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 مستقر کنید

1. ذخیره URL در متغیر INVENTORY_SERVICE_URL برای ادغام با Inventory Service

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

سرویس سفارش باید با سرویس موجودی ارتباط برقرار کند تا موجودی موجودی را تأیید کند و سفارشات قابل انجام باشند. در این مرحله URL سرویس موجودی را در متغیری ذخیره می کنید که به عنوان متغیر محیطی به سرویس سفارش ارسال می شود.

2. سرویس سفارش را مستقر کنید

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 را تست کنید

یک سند ایجاد کنید

1. URL برنامه خدمات سفارش را برای آزمایش در یک متغیر ذخیره کنید

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

2. یک درخواست سفارش بسازید و یک سفارش جدید در پایگاه داده Firestore ارسال کنید

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

خروجی نمونه

{"orderNumber":46429}

شماره سفارش را برای استفاده بعدی ذخیره کنید

export ORDER_NUMBER=<value_from_output>

مشاهده نتایج

نتایج را در Firestor مشاهده کنید

1. به کنسول Firestore بروید
2. روی Data کلیک کنید

یک سند را به روز کنید

سفارش ارسال شده شامل مقدار نبود.

1. رکورد را به روز کنید و یک جفت مقدار کلید و مقدار اضافه کنید

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"}

مشاهده نتایج

نتایج را در Firestor مشاهده کنید

3. به کنسول Firestore بروید
4. روی Data کلیک کنید

هنگام به روز رسانی ساختار NoSQL در Firestore با استفاده از patch()، فقط مواردی که در تماس ارسال می شوند به روز می شوند.

یک سند را حذف کنید

1. آیتم 46429 را از مجموعه سفارشات Firestore حذف کنید

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

مشاهده نتایج

5. به کنسول Firestore بروید
6. روی Data کلیک کنید

سند 46429 حذف شده است، اما مجموعه سفارشات باقی مانده است.

11. تبریک!

تبریک می گویم، شما آزمایشگاه را تمام کردید!

بعدش چیه:

سایر کدهای Cymbal Eats را کاوش کنید:

• راه‌اندازی گردش‌های کاری ابری با Eventarc
• راه اندازی پردازش رویداد از فضای ذخیره سازی ابری
• اتصال به Private CloudSQL از Cloud Run
• برنامه امن بدون سرور با پروکسی آگاه از هویت (IAP)
• راه اندازی Cloud Run Jobs با Cloud Scheduler
• استقرار ایمن در Cloud Run
• ایمن سازی ترافیک ورودی در اجرای ابر
• اتصال به AlloyDB خصوصی از GKE Autopilot

پاک کن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این آموزش، یا پروژه حاوی منابع را حذف کنید یا پروژه را نگه دارید و منابع فردی را حذف کنید.

حذف پروژه

ساده ترین راه برای حذف صورتحساب، حذف پروژه ای است که برای آموزش ایجاد کرده اید.