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

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

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

2. מה תלמדו

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

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

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

הגדרת סביבה בקצב אישי

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

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

  • Project name הוא השם המוצג של המשתתפים בפרויקט. זו מחרוזת תווים שלא משמשת את Google APIs. תמיד אפשר לעדכן.
  • Project ID הוא ייחודי בכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו (אי אפשר לשנות אותו אחרי שמגדירים אותו). מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי; בדרך כלל לא מעניין אותך מה זה. ברוב ה-codelabs תצטרכו להפנות למזהה הפרויקט שלכם (בדרך כלל מזוהה כ-PROJECT_ID). אם המזהה שנוצר לא מוצא חן בעיניכם, אתם יכולים ליצור מזהה אקראי אחר. לחלופין, אפשר לנסות שם משלך ולראות אם הוא זמין. לא ניתן לשנות אותו אחרי השלב הזה, והוא נשאר למשך הפרויקט.
  • לידיעתך, יש ערך שלישי, Project Number, שבו משתמשים בחלק מממשקי ה-API. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי התיעוד.
  1. בשלב הבא צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים או בממשקי API של Cloud. מעבר ב-Codelab הזה לא יעלה הרבה כסף, אם בכלל. כדי להשבית משאבים ולא לצבור חיובים מעבר למדריך הזה, אתם יכולים למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בשווי 1,200 ש"ח.

סביבת הגדרה

  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. הפעלת ממשקי ה-API של 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
  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 ב-Google כדי ליצור את הסכימה של מסד הנתונים.

  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) כדי למצוא את פרטי הכניסה של חשבון השירות שלכם.

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

ספריות הלקוח של Google Cloud CLI ו-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)

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

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

149f8bae468f8b34.png

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

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

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

כדי לראות את הגרסה שבה נעשה שימוש להרצת שאילתה בתוך gcloud spanner, יש להגדיר את הדגל – מצב שאילתה כ-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 ובוחרים באפשרות Metrics Explorer בתפריט השמאלי.
  2. בשדה Resource Type, בוחרים באפשרות Cloud Spanner Instance.
  3. בשדה Metric, בוחרים באפשרות 'ספירת שאילתות' ולוחצים על 'החלה'.
  4. בשדה Group By בוחרים באפשרות מסד נתונים, Optimize_version וסטטוס.

581b859c25790b21.png

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

Firestore הוא מסד נתונים מסוג NoSQL לאחסון מסמכים שמיועד להתאמה לעומס (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.כללים בעורך הענן
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 תיצור מזהה בשמכם, צריך להשתמש ב-method 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
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 console.
  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 console.
  2. לחיצה על 'נתונים'

cfcf78d200e15b84.png

מחיקת מסמך

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

הצגת התוצאות

  1. עוברים אל Firestore console.
  2. לחיצה על 'נתונים'

73e14d69211d1539.png

11. מעולה!

כל הכבוד, סיימת את שיעור ה-Lab!

השלב הבא:

בקישורים הבאים תוכלו למצוא עוד מעבדי קוד Labs של Cymbal Eats:

הסרת המשאבים

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

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

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