מטרות
במדריך הזה נסביר איך לבצע את השלבים הבאים באמצעות ספריית הלקוח של Spanner ל-C#:
- יוצרים מכונה ומסד נתונים ב-Spanner.
- לכתוב, לקרוא ולהריץ שאילתות SQL על נתונים במסד הנתונים.
- מעדכנים את הסכימה של מסד הנתונים.
- עדכון נתונים באמצעות טרנזקציית קריאה-כתיבה.
- מוסיפים אינדקס משני למסד הנתונים.
- משתמשים באינדקס כדי לקרוא ולהריץ שאילתות SQL על נתונים.
- אחזור נתונים באמצעות טרנזקציה לקריאה בלבד.
עלויות
במדריך הזה משתמשים ב-Spanner, רכיב שלGoogle Cloudשהשימוש בו כרוך בתשלום. למידע על עלות השימוש ב-Spanner, ראו תמחור.
לפני שמתחילים
מבצעים את השלבים שמפורטים בקטע הגדרה, שכוללים יצירה והגדרה של פרויקט Google Cloud כברירת מחדל, הפעלת החיוב, הפעלת Cloud Spanner API והגדרת OAuth 2.0 כדי לקבל פרטי כניסה לאימות לשימוש ב-Cloud Spanner API.
חשוב במיוחד להריץ את הפקודה gcloud auth
application-default login כדי להגדיר את סביבת הפיתוח המקומית עם פרטי כניסה לאימות.
הכנת סביבת C# מקומית
מגדירים את משתנה הסביבה
PROJECT_IDלמזהה הפרויקט ב- Google Cloud .קודם מגדירים את
PROJECT_IDלסשן הנוכחי של PowerShell:$env:PROJECT_ID = "MY_PROJECT_ID"
לאחר מכן, מגדירים את
PROJECT_IDלכל התהליכים שנוצרו אחרי הפקודה הזו:[Environment]::SetEnvironmentVariable("PROJECT_ID", "MY_PROJECT_ID", "User")
מורידים את פרטי הכניסה.
נכנסים לדף Credentials במסוף Google Cloud .
לוחצים על Create credentials ובוחרים באפשרות Service account key.
בקטע Service account, בוחרים באפשרות Compute Engine default service account, ומשאירים את האפשרות JSON מסומנת בקטע Key type. לוחצים על Create. המחשב מוריד קובץ JSON.
מגדירים את פרטי הכניסה. כדי להגדיר את
GOOGLE_APPLICATION_CREDENTIALSכך שיצביע על מפתח ה-JSON, מריצים את הפקודות הבאות על קובץ בשםFILENAME.jsonבספריית ההורדות שלCURRENT_USER, שנמצאת בכונןC:קודם כול, כדי להגדיר את
GOOGLE_APPLICATION_CREDENTIALSלסשן הזה של PowerShell:$env:GOOGLE_APPLICATION_CREDENTIALS = "C:\Users\CURRENT_USER\Downloads\FILENAME.json"
כדי להגדיר את
GOOGLE_APPLICATION_CREDENTIALSלכל התהליכים שנוצרו אחרי הפקודה הזו:[Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS", "C:\Users\CURRENT_USER\Downloads\FILENAME.json", "User")
משכפלים את המאגר של האפליקציה לדוגמה ומעבירים אותו למכונה המקומית:
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samplesאפשר גם להוריד את קובץ הדוגמה כקובץ ZIP ולחלץ אותו.
פותחים את
Spanner.sln, שנמצא בספרייהdotnet-docs-samples\spanner\apiשל המאגר שהורדתם, באמצעות Visual Studio 2017 או גרסה עדכנית יותר, ואז יוצרים אותו.עוברים לספרייה במאגר שהורדתם שמכילה את האפליקציה שעברה הידור. לדוגמה:
cd dotnet-docs-samples\spanner\api\Spanner
יצירת מכונה
בפעם הראשונה שמשתמשים ב-Spanner, צריך ליצור מכונה – הקצאה של משאבים שמשמשים את מסדי הנתונים של Spanner. כשיוצרים מכונה, בוחרים הגדרת מכונה שקובעת איפה הנתונים יאוחסנו, וגם את מספר הצמתים שבהם משתמשים, שקובע את כמות משאבי האחסון וההצגה במכונה.
במאמר יצירת מכונה מוסבר איך ליצור מכונה של Spanner באמצעות אחת מהשיטות הבאות. אפשר לתת למכונה את השם test-instance כדי להשתמש בה עם נושאים אחרים במסמך הזה, שמתייחסים למכונה בשם test-instance.
- Google Cloud CLI
- מסוף Google Cloud
- ספריית לקוח (C++, C#, Go, Java, Node.js, PHP, Python, Ruby או Rust)
עיון בקבצים לדוגמה
מאגר הדוגמאות מכיל דוגמה שמראה איך להשתמש ב-Spanner עם C#.
במאגר Spanner .NET ב-GitHub מוסבר איך ליצור מסד נתונים ולשנות סכימה של מסד נתונים. הנתונים משתמשים בסכימה לדוגמה שמוצגת בדף סכימה ומודל נתונים.
יצירת מסד נתונים
אמורה להופיע ההודעה:
הקוד הבא יוצר מסד נתונים ושתי טבלאות במסד הנתונים.GoogleSQL
PostgreSQL
השלב הבא הוא כתיבת נתונים במסד הנתונים.
יצירת לקוח של מסד נתונים
לפני שתוכלו לקרוא או לכתוב, אתם צריכים ליצור SpannerConnection:
אפשר לחשוב על SpannerConnection כחיבור למסד נתונים: כל האינטראקציות עם Spanner חייבות לעבור דרך SpannerConnection.
מידע נוסף זמין במאמר העזרה בנושא SpannerConnection.
כתיבת נתונים באמצעות DML
אפשר להוסיף נתונים באמצעות שפת טיפול בנתונים (DML) בטרנזקציית קריאה-כתיבה.
משתמשים ב-method ExecuteNonQueryAsync() כדי להריץ פקודת DML.
מריצים את הדוגמה באמצעות הארגומנט writeUsingDml.
dotnet run writeUsingDml $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
4 row(s) inserted...
כתיבת נתונים באמצעות מוטציות
אפשר גם להוסיף נתונים באמצעות מוטציות.
כדי להוסיף נתונים, אפשר להשתמש ב-method connection.CreateInsertCommand(), שיוצרת SpannerCommand חדש להוספת שורות לטבלה. ה-method SpannerCommand.ExecuteNonQueryAsync() מוסיפה שורות חדשות לטבלה.
הקוד הבא מראה איך להוסיף נתונים באמצעות מוטציות:
מריצים את הדוגמה באמצעות הארגומנט insertSampleData.
dotnet run insertSampleData $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Inserted data.
הרצת שאילתות על נתונים באמצעות SQL
ב-Spanner יש תמיכה בממשק SQL לקריאת נתונים, שאפשר לגשת אליו בשורת הפקודה באמצעות Google Cloud CLI או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C#.
בשורת הפקודה
מריצים את הצהרת ה-SQL הבאה כדי לקרוא את הערכים של כל העמודות מהטבלה Albums:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
תחביר Pipe ב-GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'
בתוצאה רואים:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
שימוש בספריית הלקוח של Spanner ל-C#
בנוסף להרצה של הצהרת SQL בשורת הפקודה, אפשר להנפיק את אותה הצהרת SQL באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C#.
משתמשים ב-ExecuteReaderAsync() כדי להריץ את שאילתת ה-SQL.
כך מריצים את השאילתה וניגשים לנתונים:
dotnet run querySampleData $env:PROJECT_ID test-instance example-db
התוצאה הבאה אמורה להופיע:
SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold your Peace
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified
שאילתה באמצעות פרמטר SQL
אם באפליקציה שלכם יש שאילתה שמופעלת לעיתים קרובות, אתם יכולים לשפר את הביצועים שלה על ידי הוספת פרמטרים. אפשר לשמור במטמון את השאילתה הפרמטרית שנוצרה ולהשתמש בה שוב, וכך להפחית את עלויות ההידור. למידע נוסף, קראו את המאמר שימוש בפרמטרים של שאילתות כדי להאיץ שאילתות שמבוצעות לעיתים קרובות.
הנה דוגמה לשימוש בפרמטר בסעיף WHERE כדי לשלוח שאילתה על רשומות שמכילות ערך ספציפי של LastName.
GoogleSQL
PostgreSQL
כך מריצים את השאילתה עם פרמטר וניגשים לנתונים:
dotnet run queryWithParameter $env:PROJECT_ID test-instance example-db
התוצאה הבאה אמורה להופיע:
SingerId : 12 FirstName : Melissa LastName : Garcia
עדכון הסכימה של מסד הנתונים
נניח שאתם צריכים להוסיף עמודה חדשה בשם MarketingBudget לטבלה Albums. כדי להוסיף עמודה חדשה לטבלה קיימת, צריך לעדכן את הסכימה של מסד הנתונים. ב-Spanner אפשר לעדכן את הסכימה של מסד הנתונים בזמן שמסד הנתונים ממשיך לשרת את התנועה. עדכוני סכימה לא דורשים להעביר את מסד הנתונים למצב אופליין, והם לא נועלים טבלאות או עמודות שלמות. אפשר להמשיך לכתוב נתונים במסד הנתונים במהלך עדכון הסכימה. במאמר עדכוני סכימה מוסבר איך לעדכן סכימות ואיך השינויים בסכימה משפיעים על הביצועים.
הוספת עמודה
אפשר להוסיף עמודה בשורת הפקודה באמצעות Google Cloud CLI או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C#.
בשורת הפקודה
משתמשים בפקודה הבאה של ALTER TABLE כדי להוסיף את העמודה החדשה לטבלה:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
אמורה להופיע ההודעה:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C#
משתמשים ב-CreateDdlCommand() כדי לשנות את הסכימה:
GoogleSQL
PostgreSQL
מריצים את הדוגמה באמצעות הפקודה addColumn.
dotnet run addColumn $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Added the MarketingBudget column.
כתיבת נתונים בעמודה החדשה
הקוד הבא כותב נתונים בעמודה החדשה. היא מגדירה את MarketingBudget לערך 100000 בשורה עם מפתח השורה Albums(1, 1), ולערך 500000 בשורה עם מפתח השורה Albums(2, 2).
מריצים את הדוגמה באמצעות הפקודה writeDataToNewColumn.
dotnet run writeDataToNewColumn $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Updated data.
אפשר גם להריץ שאילתת SQL כדי לאחזר את הערכים שכתבתם.
זה הקוד להרצת השאילתה:
כדי להריץ את השאילתה הזו, מריצים את הדוגמה באמצעות הארגומנט queryNewColumn.
dotnet run queryNewColumn $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
SingerId : 1 AlbumId : 1 MarketingBudget : 100000
SingerId : 1 AlbumId : 2 MarketingBudget :
SingerId : 2 AlbumId : 1 MarketingBudget :
SingerId : 2 AlbumId : 2 MarketingBudget : 500000
SingerId : 2 AlbumId : 3 MarketingBudget :
עדכון נתונים
אפשר לעדכן נתונים באמצעות DML בעסקה של קריאה וכתיבה.
משתמשים ב-method ExecuteNonQueryAsync() כדי להריץ פקודת DML.
GoogleSQL
PostgreSQL
מריצים את הדוגמה באמצעות הארגומנט writeWithTransactionUsingDml.
dotnet run writeWithTransactionUsingDml $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Transaction complete.
שימוש באינדקס משני
נניח שאתם רוצים לאחזר את כל השורות של Albums שיש בהן ערכי AlbumTitle בטווח מסוים. אפשר לקרוא את כל הערכים מהעמודה AlbumTitle באמצעות הצהרת SQL או קריאה, ואז למחוק את השורות שלא עומדות בקריטריונים. אבל סריקה של כל הטבלה היא פעולה יקרה, במיוחד בטבלאות עם הרבה שורות. במקום זאת, כדי לאחזר שורות מהר יותר כשמחפשים לפי עמודות שהן לא מפתח ראשי, אפשר ליצור אינדקס משני בטבלה.
כדי להוסיף אינדקס משני לטבלה קיימת, צריך לעדכן את הסכימה. כמו עדכוני סכימה אחרים, Spanner תומך בהוספת אינדקס בזמן שמסד הנתונים ממשיך לשרת את התנועה. Spanner ממלא באופן אוטומטי את החוסרים באינדקס באמצעות הנתונים הקיימים. מילויים חוזרים עשויים להימשך כמה דקות, אבל לא צריך להעביר את מסד הנתונים למצב אופליין או להימנע מכתיבה בטבלה שנוסף לה אינדקס במהלך התהליך הזה. למידע נוסף, קראו את המאמר הוספת אינדקס משני.
אחרי שמוסיפים אינדקס משני, Spanner משתמש בו באופן אוטומטי לשאילתות SQL שסביר להניח שיפעלו מהר יותר עם האינדקס. אם אתם משתמשים בממשק הקריאה, אתם צריכים לציין את האינדקס שבו אתם רוצים להשתמש.
הוספת אינדקס משני
אפשר להוסיף אינדקס בשורת הפקודה באמצעות ה-CLI של gcloud, או באופן פרוגרמטי באמצעות ספריית הלקוח של Spanner ל-C#.
בשורת הפקודה
משתמשים בפקודה הבאה של CREATE INDEX כדי להוסיף אינדקס למסד הנתונים:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
אמורה להופיע ההודעה:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C#
משתמשים ב-CreateDdlCommand() כדי להוסיף אינדקס:
מריצים את הדוגמה באמצעות הפקודה addIndex.
dotnet run addIndex $env:PROJECT_ID test-instance example-db
הוספת אינדקס יכולה להימשך כמה דקות. אחרי הוספת האינדקס, אמור להופיע:
Added the AlbumsByAlbumTitle index.
הוספת אינדקס לקריאות של אינדקס בלבד
אולי שמתם לב שבדוגמה הקודמת של קריאה לא נכללה קריאה של העמודה MarketingBudget. הסיבה לכך היא שממשק הקריאה של Spanner לא תומך באפשרות לצרף אינדקס לטבלת נתונים כדי לבצע חיפוש מהיר של ערכים שלא מאוחסנים באינדקס.
יוצרים הגדרה חלופית של AlbumsByAlbumTitle ששומרת עותק של MarketingBudget באינדקס.
בשורת הפקודה
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
הוספת אינדקס יכולה להימשך כמה דקות. אחרי שמוסיפים את האינדקס, אמור להופיע:
Schema updating...done.
שימוש בספריית הלקוח של Spanner ל-C#
משתמשים ב-CreateDdlCommand() כדי להוסיף אינדקס עם משפט STORING:
מריצים את הדוגמה באמצעות הפקודה addStoringIndex.
dotnet run addStoringIndex $env:PROJECT_ID test-instance example-db
אמורה להופיע ההודעה:
Added the AlbumsByAlbumTitle2 index.
עכשיו אפשר לבצע קריאה שמאחזרת את כל העמודות AlbumId, AlbumTitle ו-MarketingBudget מהאינדקס AlbumsByAlbumTitle2:
כדי לקרוא נתונים באמצעות אינדקס האחסון שיצרתם, מריצים שאילתה שמציינת במפורש את האינדקס:
מריצים את הדוגמה באמצעות הפקודה queryDataWithStoringIndex.
dotnet run queryDataWithStoringIndex $env:PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
AlbumId : 2 AlbumTitle : Forever Hold your Peace MarketingBudget : 300000
AlbumId : 2 AlbumTitle : Go, Go, Go MarketingBudget : 300000
אחזור נתונים באמצעות עסקאות לקריאה בלבד
נניח שאתם רוצים לבצע יותר מקריאה אחת באותה חותמת זמן. עסקאות לקריאה בלבד צופות בתחילית עקבית של היסטוריית ה-commit של העסקה, כך שהאפליקציה תמיד מקבלת נתונים עקביים.
משתמשים ב-TransactionScope() של .NET framework יחד עם OpenAsReadOnlyAsync() כדי להריץ עסקאות לקריאה בלבד.
כך מריצים שאילתה ומבצעים קריאה באותה טרנזקציה לקריאה בלבד:
.NET Standard 2.0
.NET Standard 1.5
מריצים את הדוגמה באמצעות הפקודה queryDataWithTransaction.
dotnet run queryDataWithTransaction $env:PROJECT_ID test-instance example-db
הפלט אמור להיראות כך:
SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk
SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk
הסרת המשאבים
כדי להימנע מחיובים נוספים בחשבון לחיוב ב-Cloud על המשאבים שבהם השתמשתם במדריך הזה, אתם צריכים למחוק את מסד הנתונים ואת המכונה שיצרתם.
מחיקת מסד הנתונים
אם מוחקים מכונה, כל מסדי הנתונים שבתוכה נמחקים באופן אוטומטי. בשלב הזה מוסבר איך למחוק מסד נתונים בלי למחוק מכונה (עדיין תחויבו על המכונה).
בשורת הפקודה
gcloud spanner databases delete example-db --instance=test-instance
באמצעות מסוף Google Cloud
נכנסים לדף Spanner Instances במסוף Google Cloud .
לוחצים על המופע.
לוחצים על מסד הנתונים שרוצים למחוק.
בדף Database details, לוחצים על Delete.
מאשרים שרוצים למחוק את מסד הנתונים ולוחצים על מחיקה.
מחיקת המכונה
מחיקת מכונה גורמת להסרה אוטומטית של כל מסדי הנתונים שנוצרו בה.
בשורת הפקודה
gcloud spanner instances delete test-instance
באמצעות מסוף Google Cloud
נכנסים לדף Spanner Instances במסוף Google Cloud .
לוחצים על המכונה.
לוחצים על Delete.
מאשרים שרוצים למחוק את המכונה ולוחצים על Delete.
המאמרים הבאים
- נסו את גרסת בטא של ספק מסד הנתונים של Spanner ל-Entity Framework Core.
במאמר אימות לשירותי Cloud באמצעות ספריות לקוח תוכלו לקרוא מידע נוסף על פרטי כניסה לאימות ולהרשאה.