מדריך בנושא ניהול גרסאות ב-Compute Engine: ממשקי API, ספריות לקוח וכלים

במדריך הזה מוסבר איך Compute Engine מנהל גרסאות ב-REST APIs, בספריות לקוח ובכלי שורת הפקודה gcloud. במאמר הזה מוסבר על ההבדל בין ניהול גרסאות מבוסס-ערוץ (CBV) לבין ניהול גרסאות מבוסס-ממשק (IBV), עם דגש על האפשרות השנייה.

לפני שמתחילים

  • אם עדיין לא עשיתם את זה, תצטרכו להגדיר אימות. אימות הוא תהליך שבו מאמתים את הזהות שלכם כדי לקבל גישה לממשקי API ולשירותים של Google Cloud . כדי להריץ קוד או דוגמאות מסביבת פיתוח מקומית, אפשר לבצע אימות ל-Compute Engine באחת מהדרכים הבאות:

    צריך לבחור את הכרטיסייה הרלוונטית לאופן שבו תכננתם להשתמש בדוגמאות בדף הזה:

    המסוף

    כשמשתמשים במסוף Google Cloud כדי לגשת לשירותים Google Cloud ולממשקי ה-API, לא צריך להגדיר אימות.

    gcloud

    1. התקינו את ה-CLI של Google Cloud. אחר כך, מאתחלים את ה-CLI של Google Cloud באמצעות הפקודה הבאה: 

      gcloud init

      אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  • הגדרת אזור ותחום כברירת מחדל

    • REST

    כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.

      התקינו את ה-CLI של Google Cloud.

      אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

    מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .

ניהול גרסאות מבוסס-ערוץ וניהול גרסאות מבוסס-ממשק

‫Compute Engine API תומך בשתי שיטות לניהול גרסאות: ניהול גרסאות מבוסס-ערוץ (CBV) וניהול גרסאות מבוסס-ממשק (IBV).

  • בניהול גרסאות מבוסס-ערוץ, הגרסאות הן לטווח ארוך ומקבלות עדכונים במקום. ‫Compute Engine תומך בערוצים v1, בטא ואלפא.

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

האימות באמצעות שיחת וידאו (IBV) מחליף את האימות באמצעות שיחת טלפון (CBV). עם זאת, הטמעות קיימות של CBV לא מושפעות מההשקה של IBV ומהגרסאות החדשות. אתם יכולים להמשיך להשתמש ב-CBV אם אתם מעדיפים להישאר בגרסת ה-API הקיימת.

ה-IBV עוזר לכם לוודא שההתנהגות של ה-API, והמטען הייעודי (payload) של הבקשה והתגובה שלו, תואמים לגרסת ה-API המיועדת. כדי להשתמש ב-IBV, צריך לציין גרסת API בבקשה באמצעות פרמטר שאילתה או כותרת. מידע נוסף מופיע במאמר בנושא יצירת בקשת API.

היתרונות של שימוש ב-IBV:

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

מידע נוסף על אסטרטגיות של ניהול גרסאות זמין בהצעה לשיפור API מספר 185.

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

כל גרסה של Compute Engine IBV API היא אוסף של שינויים בממשק שמשתפים את אותה גרסת שירות, למרות שממשקים עשויים לשנות גרסה באופן עצמאי.

‫Compute Engine IBV API תומך בגרסאות יציבות ובגרסאות Preview.

גרסאות יציבות

רוב הגרסאות של ה-API הן גרסאות יציבות. בגרסאות יציבות נשמרת תאימות קפדנית, כפי שמוגדר ב-AIP-180. כלומר, גרסאות יציבות חדשות יותר של אותה גרסה לא משבשות פונקציונליות קיימת ולא דורשות שכתוב של קוד.

‫Compute Engine מזהה גרסאות API יציבות באמצעות תאריכים בפורמט YYYY-MM-DD (לדוגמה, 2026-09-01). תאריכים מאוחרים יותר מציינים גרסאות חדשות יותר.

‫Compute Engine תומך בגרסאות יציבות לאורך פרקי זמן ארוכים, כדי שמערכות הייצור שלכם יישארו מהימנות ורציפות. ברוב האפליקציות, מספיק להשתמש בגרסה יציבה אחת כדי לבצע את המשימות היומיומיות.

גרסאות טרום-השקה (Preview)

‫Compute Engine יכול לפרסם גרסאות טרום-השקה כדי לקבל משוב מוקדם מהמשתמשים על תכונות חדשות. בגרסאות תצוגה מקדימה, התאריך מסתיים בתג -preview (לדוגמה, 2026-10-01-preview).

גרסאות התצוגה המקדימה כוללות את כל היכולות מהגרסה היציבה האחרונה, בנוסף לתכונות ניסיוניות חדשות. כשמשתמשים בגרסאות בתצוגה מקדימה, חשוב לזכור את הנקודות הבאות:

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

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

ציון גרסת API בבקשה

כדי לבצע קריאות ל-API באמצעות IBV, צריך לציין בבקשות גרסת יעד באמצעות פרמטר של שאילתה או כותרת. דוגמאות לאופן שליחת בקשות API מופיעות במאמר יצירת בקשת API.

ספריות לקוח ב-Cloud

ספריות הלקוח של Cloud מפשטות את התהליך של יצירת קריאות REST גולמיות וניתוח שלהן. כל גרסה של הספרייה מתחברת ישירות לגרסה ספציפית של API שמבוססת על תאריך.

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

מומלץ להפעיל אפליקציות בסביבת הייצור באמצעות ספריות לקוח יציבות ב-Cloud, ולהשתמש בספריות בתצוגה מקדימה רק בסביבות בדיקה.

‫Google Cloud CLI ‏ (gcloud)

בעזרת gcloud CLI אפשר לנהל משאבים של Compute Engine בלי לעקוב אחרי נקודות קצה נפרדות של REST באופן ידני.

ממשק ה-CLI של gcloud מחלק את הפקודות לשתי קטגוריות:

  • פקודות יציבות: פקודות רגילות (כמו gcloud compute instances create) מטרגטות גרסאות יציבות של API. הפקודות האלה נתמכות באופן מלא, צפויות ומומלצות לשימוש בתסריטים של שלב הייצור.
  • פקודות בתצוגה מקדימה: תכונות בגישה מוקדמת משתמשות בקבוצה gcloud preview (למשל gcloud preview compute ...). הפקודות האלה מציגות אזהרה קצרה כי החוזים עשויים להשתנות לפני השחרור הסופי.

Terraform

ה- Google Cloud Terraform Provider מבצע הפשטה של ניהול גרסאות API ומנהל אינטראקציות בסיסיות עם API. הגדרות Terraform לא חושפות או דורשות הגדרות ידניות של כותרת גרסה.

כדי לקבל גישה לתכונות חדשות, צריך לעדכן את Google Cloud Terraform Provider לגרסה האחרונה. לתכונות בגרסת טרום-השקה, משתמשים בפלאגין שמתממשק עם שירותים חיצוניים google-beta.

שאלות נפוצות

בקטע הזה מפורטות תשובות לשאלות נפוצות בנושא ניהול גרסאות של Compute Engine API.

  • האם צריך לעבור מגרסה 1 (CBV) ל-IBV?

    לא, בקשות קיימות ל-API של גרסה 1 של CBV ממשיכות לפעול כמו קודם. עם זאת, לא תהיה לכם גישה לתכונות חדשות שזמינות ב-IBV API.

  • כמה זמן תהיה תמיכה בגרסה של IBV API?

    גרסאות יציבות נשמרות ללא הגבלת זמן בהתאם למדיניות הרגילה Google Cloudבנושא הוצאה משימוש.

  • מה התדירות שבה מתפרסמות גרסאות חדשות של IBV API?

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

  • האם צריך להפעיל משהו ב Google Cloud מסוף?

    לא, IBV API מופעל כברירת מחדל עם Compute Engine API.

  • מה קורה אם לא מציינים גרסה בבקשה?

    הבקשה שלך מוגדרת כברירת מחדל לנקודת הקצה CBV v1.

  • איפה אפשר למצוא את גרסת ה-API ברשומות של יומני הביקורת של Cloud?

    גרסת ה-API נרשמת ביומן בפרמטר protoPayload.requestMetadata.callerSuppliedUserAgent ובכותרות הבקשה או בפרמטרים של השאילתה.

המאמרים הבאים

למידע נוסף על Compute Engine API, אפשר לקרוא את המאמרים הבאים: