התחברות למסדי נתונים מנוהלים מ-Cloud Run

1. סקירה כללית

בשיעור ה-Lab הזה תלמדו איך לשלב מסדי נתונים ללא שרתים(Spanner ו-Firestore) עם אפליקציות(Go ו-Node.js) שפועלות ב-Cloud Run. האפליקציה Cymbal Eats כוללת כמה שירותים שפועלים ב-Cloud Run. בשלבים הבאים תגדירו את השירותים כך שישתמשו במסד הנתונים הרלציוני Cloud Spanner ובמסד הנתונים של מסמכי NoSQL‏ Cloud Firestore. שימוש במוצרים ללא שרתים בשביל שכבת הנתונים וזמן הריצה של האפליקציה מאפשר לכם להסתיר את כל ניהול התשתית, ולהתמקד בפיתוח האפליקציה במקום לדאוג להוצאות התקורה.

2. מה תלמדו

בשיעור Lab זה תלמדו איך:

  • שילוב של Spanner
  • הפעלת שירותים מנוהלים של Spanner
  • שילוב בקוד
  • פריסת קוד שמתחבר ל-Spanner
  • שילוב של Firestore
  • הפעלת שירותים מנוהלים של Firestore
  • שילוב בקוד
  • פריסת קוד שמתחבר ל-Firestore

3. הגדרה ודרישות

הגדרת סביבה בקצב עצמי

  1. נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

  • שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
  • מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא תישאר לאורך הפרויקט.
  • לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.
  1. בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

הגדרת הסביבה

  1. יצירת משתנה של מזהה פרויקט
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
  1. הפעלת ממשקי 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
  1. שכפול המאגר
git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git
  1. עוברים לספרייה
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.
  1. בודקים אם מופע 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) של Google Standard SQL כדי ליצור את סכימת מסד הנתונים.

  1. יצירת קובץ DDL
echo "CREATE TABLE InventoryHistory (ItemRowID STRING (36) NOT NULL, ItemID INT64 NOT NULL, InventoryChange INT64, Timestamp TIMESTAMP) PRIMARY KEY(ItemRowID)" >> table.ddl
  1. יצירת מסד הנתונים של 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
  1. צפייה בסכימה של מסד הנתונים
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, ממשקי API ל-REST וממשקי API ל-RPC, שמאפשרים לכם לשלב את Spanner בכל אפליקציה.

בקטע הבא תשתמשו בספריית הלקוח של Go כדי להתקין, לאמת ולשנות נתונים ב-Spanner.

התקנה של ספריית הלקוח

ספריית הלקוח של Cloud Spanner מקלה על השילוב עם Cloud Spanner, כי היא משתמשת אוטומטית ב-Application Default Credentials ‏ (ADC) כדי למצוא את פרטי הכניסה של חשבון השירות.

מגדירים אימות

ה-CLI של Google Cloud וספריות הלקוח ב-Google Cloud מזהים באופן אוטומטי מתי הם פועלים ב-Google Cloud, ומשתמשים בחשבון השירות של זמן הריצה של הגרסה הנוכחית של Cloud Run. השיטה הזו נקראת Application Default Credentials (אישורי ברירת מחדל של אפליקציות) והיא מאפשרת ניידות של קוד בין סביבות שונות.

עם זאת, מומלץ ליצור זהות ייעודית על ידי הקצאת חשבון שירות שמנוהל על ידי משתמש במקום חשבון השירות שמוגדר כברירת מחדל.

  1. מקצים לחשבון השירות את התפקיד 'אדמין של מסד נתונים ב-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. אפשר להשתמש בלקוח במקביל, חוץ משיטת הסגירה שלו.

קטע הקוד שלמטה יוצר לקוח Spanner

main.go

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

אפשר לחשוב על Client כעל חיבור למסד נתונים: כל האינטראקציות שלכם עם Cloud Spanner חייבות לעבור דרך Client. בדרך כלל יוצרים אובייקט Client כשהאפליקציה מופעלת, ואז משתמשים באובייקט הזה שוב כדי לקרוא, לכתוב ולהריץ עסקאות. כל לקוח משתמש במשאבים ב-Cloud Spanner.

שינוי נתונים

יש כמה דרכים להוסיף, לעדכן ולמחוק נתונים ממסד נתונים של Spanner. בהמשך מפורטות השיטות הזמינות.

בשיעור ה-Lab הזה נשתמש במוטציות כדי לשנות נתונים ב-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. לוחצים על 'פתיחת טרמינל'.
  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
  1. שמירת כתובת ה-URL של השירות
INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
  --platform managed \
  --region $REGION \
  --format=json | jq \
  --raw-output ".status.url")

בדיקת אפליקציית Cloud Run

הוספת פריט

  1. ב-Cloud Shell, מזינים את הפקודה הבאה.
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. מושגים ב-Spanner

‫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 instances.
  2. מעבר למכונות של Cloud Spanner
  3. לוחצים על השם של מכונת Cloud Spanner. בקטע 'מסדי נתונים', בוחרים את מסד הנתונים שרוצים לשלוח אליו שאילתה.
  4. לוחצים על Query (שאילתה).
  5. מזינים את השאילתה הבאה בעורך השאילתות
SELECT * FROM InventoryHistory WHERE ItemID=1
  1. לוחצים על RUN (הפעלה).
  2. לוחצים על הסבר.

במסוף Cloud מוצג תוכנית ביצוע חזותית של השאילתה.

149f8bae468f8b34.png

כלי אופטימיזציית השאילתות

הכלי לאופטימיזציה של שאילתות ב-Cloud Spanner משווה בין תוכניות ביצוע חלופיות ובוחר את התוכנית היעילה ביותר. עם הזמן, כלי האופטימיזציה של השאילתות ישתכלל, ירחיב את האפשרויות בתוכנית להרצת השאילתות וישפר את הדיוק של ההערכות שעל פיהן מתקבלות ההחלטות האלה, וכך יביא לתוכניות יעילות יותר להרצת השאילתות.

מערכת Cloud Spanner מפיצה עדכוני אופטימיזציה כגרסאות חדשות של אופטימיזציית שאילתות. כברירת מחדל, כל מסד נתונים מתחיל להשתמש בגרסה העדכנית ביותר של הכלי לאופטימיזציה לא לפני 30 יום אחרי שהגרסה הזו הושקה.

כדי לראות את הגרסה שבה נעשה שימוש כשמריצים שאילתה ב-gcloud spanner, מגדירים את הדגל ‎–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:

עדכון גרסת האופטימיזציה

הגרסה החדשה ביותר בזמן כתיבת שיעור Lab הזה היא גרסה 4. בשלב הבא, מעדכנים את טבלת Spanner כך שתשתמש בגרסה 4 של הכלי לאופטימיזציה של שאילתות.

  1. עדכון הכלי לאופטימיזציה
gcloud spanner databases ddl update $SPANNER_DB \
--instance=$SPANNER_INSTANCE \
--ddl='ALTER DATABASE InventoryHistory
SET OPTIONS (optimizer_version = 4)'

פלט לדוגמה

Schema updating...done.
  1. מזינים את הפקודה הבאה כדי לראות את עדכון הגרסה של הכלי לאופטימיזציה
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

אפשר להשתמש ב-Metrics Explorer במסוף Cloud כדי להציג באופן חזותי את מספר השאילתות של מופע מסד הנתונים. אפשר לראות באיזו גרסה של הכלי לאופטימיזציה נעשה שימוש בכל מסד נתונים.

  1. עוברים אל Monitoring ב-Cloud Console ובתפריט הימני בוחרים באפשרות Metrics Explorer.
  2. בשדה Resource type, בוחרים באפשרות Cloud Spanner Instance.
  3. בשדה Metric, בוחרים באפשרות Count of queries (מספר השאילתות) ולוחצים על Apply (החלה).
  4. בשדה Group By (קיבוץ לפי), בוחרים באפשרויות database (מסד נתונים), optimizer_version (גרסת האופטימיזציה) ו-status (סטטוס).

581b859c25790b21.png

7. יצירה והגדרה של מסד נתונים ב-Firestore

‫Firestore הוא מסד נתונים מסוג NoSQL לאחסון מסמכים שמיועד להתאמה לעומס (automatic scaling), לביצועים גבוהים ולפיתוח אפליקציות בקלות. לממשק של Firestore יש הרבה תכונות דומות לאלה של מסדי נתונים מסורתיים, אבל מסד נתונים של NoSQL שונה מהם בתיאור של הקשרים בין אובייקטים של נתונים.

במשימה הבאה נסביר איך ליצור אפליקציית שירות הזמנות ב-Cloud Run עם תמיכה של Firestore. שירות ההזמנות יקרא לשירות המלאי שנוצר בקטע הקודם כדי לשלוח שאילתה למסד הנתונים של Spanner לפני תחילת ההזמנה. השירות הזה יבטיח שיש מספיק מלאי ושאפשר למלא את ההזמנה.

6843abaf4263e112.png

8. מושגים ב-Firestore

מודל נתונים

מסד נתונים ב-Firestore מורכב מאוספים וממסמכים.

b60acd63d4793a6c.png

מסמכים

כל מסמך מכיל קבוצה של צמדי מפתח/ערך. ‫Firestore מותאם לאחסון של אוספים גדולים של מסמכים קטנים.

5571cb2f261d2dbe.png

אוספים

חובה לשמור את כל המסמכים באוספים. מסמכים יכולים להכיל אוספי משנה ואובייקטים מוטמעים, כולל שדות פרימיטיביים כמו מחרוזות או אובייקטים מורכבים כמו רשימות.

5811378cb721e5ec.png

יצירה של מסד נתונים ב-Firestore

  1. יצירת מסד נתונים ב-Firestore
gcloud firestore databases create --location=$REGION

פלט לדוגמה

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

9. שילוב של Firestore באפליקציה

בקטע הזה תעדכנו את חשבון השירות, תוסיפו חשבונות שירות לגישה ל-Firestore, תבדקו ותפרוסו את כללי האבטחה של Firestore ותבדקו איך הנתונים משתנים ב-Firestore.

מגדירים אימות

  1. הקצאת התפקיד 'משתמש ב-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

כללי האבטחה מספקים בקרת גישה ואימות נתונים בפורמט ברור ופשוט.

  1. עוברים לספרייה order-service/starter-code
cd ~/cymbal-eats/order-service
  1. פותחים את הקובץ 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. לצורך שיעור ה-Lab הזה, כל הקריאות מותרות. זו לא הגדרת ייצור מומלצת.

הפעלת שירותים מנוהלים של Firestore

  1. לוחצים על 'פתיחת טרמינל'.
  2. יוצרים קובץ ‎ .firebaserc עם מזהה הפרויקט הנוכחי. ההגדרות של יעדי הפריסה מאוחסנות בקובץ ‎ .firebaserc בספריית הפרויקט.

firebaserc.tmpl

sed "s/PROJECT_ID/$PROJECT_ID/g" firebaserc.tmpl > .firebaserc
  1. הורדת קובץ בינארי של 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!
  1. פריסת כללי 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 יוצר באופן אוטומטי את מזהה המסמך.
  • יוצרים מסמך ריק עם מזהה שנוצר באופן אוטומטי, ומקצים לו נתונים בשלב מאוחר יותר.

בקטע הבא נסביר איך ליצור מסמך באמצעות שיטת ההגדרה.

הגדרת מסמך

משתמשים ב-method‏ 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

  1. אחסון כתובת ה-URL במשתנה INVENTORY_SERVICE_URL כדי לשלב עם שירות המלאי
INVENTORY_SERVICE_URL=$(gcloud run services describe inventory-service \
 --region=$REGION \
 --format=json | jq \
 --raw-output ".status.url")
  1. פריסת שירות ההזמנות
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")
  1. יצירת בקשה להזמנה ופרסום הזמנה חדשה במסד הנתונים של 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

  1. עוברים אל מסוף Firestore.
  2. לוחצים על 'נתונים'.

465ceca6198b2b88.png

עדכון מסמך

ההזמנה שנשלחה לא כללה את הכמות.

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

הצגת התוצאות

צפייה בתוצאות ב-Firestore

  1. עוברים אל מסוף Firestore.
  2. לוחצים על 'נתונים'.

cfcf78d200e15b84.png

מחיקת מסמך

  1. מחיקת פריט 46429 מהאוסף orders ב-Firestore
curl --location -g --request DELETE $ORDER_SERVICE_URL/order/${ORDER_NUMBER}

הצגת התוצאות

  1. עוברים אל מסוף Firestore.
  2. לוחצים על 'נתונים'.

73e14d69211d1539.png

‫11. מעולה!

כל הכבוד, סיימתם את ה-Lab.

השלב הבא:

כדאי לעיין במדריכי Codelab נוספים של Cymbal Eats:

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים בנפרד.

מחיקת הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.