יצירת הגדרת API

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

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

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

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

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

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

יצירת הגדרת API

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

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

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

מסוף Google Cloud

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

Google Cloud CLI

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

  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: 1111111@developer.gserviceaccount.com
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, אלא רק לעדכן את התוויות ואת השם לתצוגה.

מסוף 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 בשער.

מסוף 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

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