יצירת הגדרת API

בדף הזה מוסבר איך ליצור הגדרת API לפריסה ב-API Gateway.

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

לפני שיוצרים הגדרת API, צריך:

• מכינים את סביבת הפיתוח כמו שמתואר במאמר הגדרת סביבת הפיתוח.

• יוצרים הגדרת API כמפרט OpenAPI.

• אם משתמשים ב-Google Cloud CLI, אפשר ליצור API. אם ה-API לא קיים, יצירת ההגדרה של ה-API יוצרת אותו.

  הערה: כשמשתמשים במסוף Google Cloud , ה-API והגדרות ה-API נוצרים כשפורסים את ה-API בשער.

דרישות לגבי מזהה הגדרת ה-API

בפקודות רבות של ה-CLI של gcloud שמוצגות כאן צריך לציין את מזהה ההגדרה של ה-API, בפורמט: CONFIG_ID. ‫API Gateway אוכף את הדרישות הבאות לגבי מזהה הגדרת ה-API:

• האורך המקסימלי הוא 63 תווים.
• השם צריך להכיל רק אותיות קטנות, מספרים או מקפים.
• השם לא יכול להתחיל במקף.
• אסור להכיל קו תחתון.

יצירת הגדרת API

יוצרים הגדרת API על ידי העלאה של הגדרת ה-API.

הערה: API Gateway תומך ביצירת הגדרות API כמפרטי OpenAPI לכל שירותי ה-Backend הזמינים. ‫API Gateway תומך גם בשימוש בהגדרות ובמפרטים של שירותי gRPC עבור שירותי gRPC ב-Cloud Run.

אם הערך של managedService בהגדרת ה-API מוגדר לשירות ESPv2 Beta, צריך לוודא שהשדה host (OpenAPI 2.0) או השדה server.url (OpenAPI 3.x) מוגדרים כתוסף x-google-endpoint בהגדרת ה-API.

כדי ליצור הגדרת API:

מסוף Google Cloud

יוצרים הגדרת API כשפורסים API בשער.

Google Cloud CLI

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

הערה: אם רוצים להשתמש ב-OpenAPI 3.x, צריך לעדכן את הרכיבים של ה-CLI של gcloud לפני שיוצרים הגדרת API, כדי למנוע שגיאות כשמעלים את הגדרת ה-API.

1. עוברים לספרייה שמכילה את הגדרת ה-API.

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

   מידע נוסף על יצירת הגדרה והגדרת שירות gRPC להגדרת ה-API זמין במאמרים הגדרת שירות gRPC ותחילת השימוש ב-API Gateway וב-Cloud Run for gRPC.

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

   gcloud config list project

   אם אתם צריכים לשנות את פרויקט ברירת המחדל, מריצים את הפקודה הבאה ומחליפים את PROJECT_ID במזהה הפרויקט שבו אתם רוצים ליצור את השירות: Google Cloud

   gcloud config set project PROJECT_ID

3. הצגת העזרה עבור הפקודה api-configs create:

   gcloud api-gateway api-configs create --help

4. מריצים את הפקודה הבאה כדי ליצור את הגדרות ה-API:

   gcloud api-gateway api-configs create CONFIG_ID \
         --api=API_ID --openapi-spec=API_DEFINITION \
         --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   where:

   • ‫CONFIG_ID מציין את המזהה של הגדרת ה-API החדשה.
   • ‫API_ID מציין את המזהה של ה-API של API Gateway שמשויך להגדרת ה-API הזו. אם ה-API עדיין לא קיים, הפקודה הזו יוצרת אותו.
   • ‫API_DEFINITION מציין את השם של מפרט OpenAPI שמכיל את הגדרת ה-API.
   • ‫SERVICE_ACCOUNT_EMAIL מציין את חשבון השירות שמשמש לחתימה על אסימונים עבור שרתי קצה עורפיים שהוגדר להם אימות. פרטים נוספים זמינים במאמר הגדרת חשבון השירות שמשמש ליצירת הגדרות API.

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

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

   gcloud api-gateway api-configs describe CONFIG_ID \
         --api=API_ID

   הפקודה הזו מחזירה את הפלט הבא:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
         backendConfig:
           googleServiceAccount: [e-mail]
   labels: ''
   name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   serviceRollout:
         rolloutId: 2020-02-04r2
   state: ACTIVE
   updateTime: '2020-02-04T18:33:12.219323647Z'

6. מפעילים את ה-API באמצעות שם השירות המנוהל של ה-API. אפשר למצוא את הערך הזה בעמודה Managed Service (שירות מנוהל) של ה-API בדף הנחיתה של ממשקי ה-API:

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

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

ה-CLI של gcloud מקבל הרבה אפשרויות, כולל אלה שמתוארות בהפניה ל-Google Cloud CLI. בנוסף, ב-API Gateway אפשר להגדיר את האפשרויות הבאות כשיוצרים הגדרת API:

• ‫--async: החזרת השליטה למסוף באופן מיידי, בלי להמתין לסיום הפעולה.
• ‫--display-name=NAME: מציין את שם התצוגה של הגדרת ה-API, כלומר השם שמוצג בממשק המשתמש. לא משתמשים ברווחים בשם. במקום זאת, אפשר להשתמש במקפים ובקווים תחתונים. ערך ברירת המחדל הוא CONFIG_ID.
• ‫--labels=KEY1=VALUE1,KEY2=VALUE2,...: מציין את התוויות שמשויכות להגדרת ה-API.

לדוגמה:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

אפשר לראות את התוויות בפלט של הפקודה describe שמוצגת, או בפקודה list על ידי הכללת האפשרות --format:

gcloud api-gateway api-configs list \
  --api=API_ID --format="table(name, labels)"

רשימת הגדרות API

הצגת רשימה של כל נכסי API Gateway שנפרסו בפרויקט Google Cloud .

מסוף Google Cloud

כדי להציג רשימה של הגדרות API עבור API ספציפי בפרויקט:

1. נכנסים לדף API Gateway במסוף Google Cloud .

   ל-API Gateway

2. לוחצים על ממשק ה-API הנדרש.
3. לוחצים על הכרטיסייה Configs.

בדף תוצג רשימה של הגדרות API זמינות.

Google Cloud CLI

כדי להציג רשימה של הגדרות API לפרויקט ספציפי:

gcloud api-gateway api-configs list 

הפקודה הזו מחזירה את הפלט הבא:

NAME                                                                                                 DISPLAY_NAME             ROLLOUT_ID    STATE     CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

כדי להציג רשימה של הגדרות API עבור API ספציפי בפרויקט:

gcloud api-gateway api-configs list --api=API_ID 

משתמשים ב-API ובמזהי ההגדרות כדי לקבל מידע מפורט על הגדרות ה-API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID 

עדכון הגדרות של API

אי אפשר לשנות הגדרת API קיימת, אלא רק לעדכן את התוויות ואת השם לתצוגה שלה.

הערה: בכל פעם שמעלים הגדרת API, ‏ API Gateway יוצר הגדרת API חדשה.

כדי לעדכן הגדרת API:

1. מעדכנים את המפרט של OpenAPI שמכיל את הגדרת ה-API.
2. מעלים את הגדרת ה-API כדי ליצור הגדרת API חדשה.

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

מסוף Google Cloud

1. נכנסים לדף API Gateway במסוף Google Cloud .

   ל-API Gateway

2. לוחצים על ממשק ה-API הנדרש.
3. לוחצים על הכרטיסייה Configs.
4. לוחצים על הגדרת ה-API הנדרשת.
5. לוחצים על עריכה עריכה.
6. עורכים את השם המוצג או את התוויות.
7. לוחצים על Save.

Google Cloud CLI

כדי לעדכן הגדרת API קיימת, משתמשים בפקודה הבאה של gcloud:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

לדוגמה:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID \
  --update-labels=a=1,b=2

כדי לראות את כל אפשרויות העדכון, משתמשים בפקודה הבאה:

gcloud api-gateway api-configs update --help

מחיקת הגדרת API

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

לפני שמוחקים הגדרת API שנמצאת בשימוש, צריך:

• פריסת הגדרת API שונה בשער.
• מחיקת השער.

מידע נוסף זמין במאמר פריסת API בשער.

מסוף Google Cloud

1. נכנסים לדף API Gateway במסוף Google Cloud .

   ל-API Gateway

2. לוחצים על ממשק ה-API הנדרש.
3. לוחצים על הכרטיסייה Configs.
4. לוחצים על סמל האפשרויות הנוספות ואז על מחיקה כדי למחוק את הגדרת ה-API שנבחרה.

Google Cloud CLI

כדי למחוק קובץ הגדרות API קיים, משתמשים בפקודה הבאה של gcloud CLI:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

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

• פריסת API בשער