פריסת API שמנוהל על ידי Cloud Endpoints

פריסת API שמנוהל על ידי Cloud Endpoints

במדריך למתחילים הזה מוסבר איך לפרוס API לדוגמה שמנוהל על ידי Cloud Endpoints. קוד לדוגמה כולל:

• API בארכיטקטורת REST שאפשר להריץ עליו שאילתות כדי למצוא את השם של נמל תעופה לפי קוד IATA בן שלוש אותיות.
• סקריפט שמעלה את הגדרות ה-API ל-Endpoints.
• סקריפט שפורס קצה עורפי של סביבה גמישה ב-App Engine כדי לארח את ה-API לדוגמה.

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

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

• Cloud Endpoints for OpenAPI: Tutorials
• Cloud Endpoints for gRPC: Tutorials
• מסגרות של Cloud Endpoints: מדריכים

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לפריסה ולניהול של API, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

• פריסת ההגדרה של Endpoints: אדמין לניהול שירותים (roles/servicemanagement.admin)
• הפעלת השירותים הנדרשים: Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
• יוצרים את אפליקציית App Engine: App Engine Creator (roles/appengine.appCreator)
• פורסים את ה-API לדוגמה ב-App Engine:
  • ‫App Engine Deployer (roles/appengine.deployer)
  • עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
  • משתמש באובייקטים באחסון (roles/storage.objectUser)
  • משתמש בחשבון שירות (roles/iam.serviceAccountUser)

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

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

הפעלת Cloud Shell

1. במסוף Google Cloud , מוודאים שאתם נמצאים בפרויקט שבו אתם רוצים להשתמש ב-API לדוגמה.

2. פותחים את Cloud Shell.

   פתיחת Cloud Shell

   בחלק התחתון של מסוףGoogle Cloud ייפתח סשן של Cloud Shell בתוך מסגרת חדשה, ותופיע הודעה של שורת הפקודה. הסשן יופעל תוך כמה שניות.

   

3. אם משתמשים בפרויקט קיים, מוודאים שיש את הגרסה העדכנית של כל רכיבי gcloud המערכת המותקנים:

   gcloud components update
   

הערה: אם אתם משתמשים במכונת Linux או macOS ורוצים לבצע את ההפעלה המהירה הזו באמצעות מעטפת מקומית, אתם צריכים להוריד את Google Cloud CLI ולבצע את ההוראות של ההפעלה המהירה באמצעות ממשק שורת הפקודה המקומי במקום Cloud Shell.

קבלת הקוד לדוגמה

1. ב-Cloud Shell, מזינים את הפקודה הבאה כדי לקבל את דוגמת ה-API והסקריפטים:

git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart

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

cd endpoints-quickstart

פריסת ההגדרה של נקודות הקצה

כדי לפרסם API בארכיטקטורת REST ב-Endpoints, נדרש קובץ הגדרה של OpenAPI שמתאר את ה-API. ממשק ה-API לדוגמה מגיע עם קובץ OpenAPI שהוגדר מראש בשם openapi.yaml.

‫Endpoints משתמש ב-Service Management, שירות תשתית שלGoogle Cloud , כדי ליצור ולנהל ממשקי API ושירותים. כדי להשתמש ב-Endpoints לניהול API, צריך לפרוס את קובץ ההגדרות של ה-API בפורמט OpenAPI ב-Service Management.

כדי לפרוס את ההגדרה של Endpoints:

1. ב-Cloud Shell, בספרייה endpoints-quickstart, מזינים את הפקודה הבאה:

cd scripts

1. מריצים את הסקריפט הבא, שכלול בדוגמה:

./deploy_api.sh

‫Endpoints משתמש בשדה host בקובץ ההגדרות של OpenAPI כדי לזהות את השירות. הסקריפט deploy_api.sh מגדיר את המזהה של פרויקטGoogle Cloud כחלק מהשם שמוגדר בשדה host. כשמכינים קובץ הגדרות OpenAPI לשירות משלכם, צריך לעשות את זה באופן ידני.

לאחר מכן הסקריפט פורס את הגדרת ה-OpenAPI ל-Service Management באמצעות הפקודה: gcloud endpoints services deploy openapi.yaml

במהלך היצירה וההגדרה של השירות, Service Management מוציא מידע אל מסוף Google Cloud . אפשר להתעלם מהאזהרות לגבי הנתיבים ב-openapi.yaml שלא דורשים מפתח API. בסיום מוצלח, תופיע שורה שדומה לזו, שבה מוצג מזהה הגדרת השירות ושם השירות:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

הפעלת שירותים נדרשים

כדי להשתמש ב-Endpoints, צריך להפעיל לפחות את שירותי Google הבאים:

שם	כותרת
servicecontrol.googleapis.com	Service Control API
servicemanagement.googleapis.com	Service Management API

ברוב המקרים, פריסת ההגדרה של Endpoints מפעילה את השירותים הנדרשים האלה.

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

gcloud services list

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

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

צריך גם להפעיל את שירות Endpoints:

gcloud services enable YOUR-PROJECT-ID.appspot.com

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

פריסת ה-API backend

עד עכשיו פרסתם את הגדרת OpenAPI ל-Service Management, אבל עדיין לא פרסתם את הקוד כדי להפעיל את ה-Backend של ה-API. הסקריפט deploy_app.sh שכלול בדוגמה יוצר סביבה גמישה של App Engine לאירוח הקצה העורפי של ה-API, ואז הסקריפט פורס את ה-API ב-App Engine.

כדי לפרוס את העורף של ה-API:

• ב-Cloud Shell, בספרייה endpoints-quickstart/scripts, מריצים את הסקריפט הבא:

./deploy_app.sh

הסקריפט מריץ את הפקודה הבאה כדי ליצור סביבה גמישה של App Engine באזור us-central: gcloud app create --region="$REGION"

יצירת הקצה העורפי של הסביבה הגמישה של App Engine נמשכת כמה דקות. אחרי יצירת האפליקציה, הפלט הוא:

Success! The app is now created.

לאחר מכן, הסקריפט מריץ את הפקודה gcloud app deploy כדי לפרוס את ה-API לדוגמה ב-App Engine.

הפלט שיתקבל:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

תהליך הפריסה של ה-API ב-App Engine נמשך כמה דקות. כשה-API נפרס בהצלחה ב-App Engine, הפלט הוא:

Deployed service [default] to [https://example-project.appspot.com]

שליחת בקשות ל-API

• ב-Cloud Shell, אחרי פריסת ה-API לדוגמה, אפשר לשלוח אליו בקשות על ידי הפעלת הסקריפט הבא:

./query_api.sh

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

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

ה-API מצפה לפרמטר שאילתה אחד, iataCode, שמוגדר לקוד שדה תעופה תקף של IATA, כמו SEA או JFK. לדוגמה:

./query_api.sh JFK

הערה: יכול להיות שיעברו כמה דקות עד ש-App Engine יגיב לבקשות בהצלחה. אם שולחים בקשה ומתקבלת שגיאת שרת מסוג HTTP 502,‏ 503 או שגיאה אחרת, צריך להמתין דקה ולנסות לשלוח את הבקשה שוב.

הרגע פרסתם ובדקתם API ב-Endpoints!

הערה: אם אתם רוצים לספר לנו מה אהבתם במדריך הזה, אתם יכולים לשלוח משוב בתחתית הדף. המשוב שלכם עוזר לנו לשפר את המדריכים האלה.
אם קיבלתם שגיאה, הצטרפו לgoogle-cloud-endpointsקבוצת Google וספרו לנו מה השתבש. הקבוצה הזו מקבלת תשובות ממשתמשי Endpoints אחרים ומהמהנדסים של Google שעוקבים אחרי הקבוצה.

מעקב אחר פעילות ב-API

באמצעות ממשקי API שנפרסו עם Endpoints, אתם יכולים לעקוב אחרי מדדי פעולות קריטיות ב Google Cloud מסוף, ולקבל תובנות לגבי המשתמשים והשימוש באמצעות Cloud Logging.

1. ב-Cloud Shell, מריצים את סקריפט יצירת התנועה כדי לאכלס את הגרפים והיומנים:

./generate_traffic.sh

Note: This script generates requests in a loop and automatically times out
in 5 minutes. To end the script sooner, enter `Control+C` in
Cloud Shell.

1. במסוף Google Cloud , בודקים את גרפי הפעילות של ה-API.

   לדף Endpoints Services

   יכול להיות שיעברו כמה רגעים עד שהבקשות יופיעו בתרשימים. בזמן ההמתנה להצגת הנתונים:

   • אם החלונית הצדדית 'הרשאות' לא פתוחה, לוחצים על +הרשאות. בחלונית Permissions (הרשאות) אפשר לקבוע למי תהיה גישה ל-API ומה תהיה רמת הגישה.

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

   • לוחצים על סקירה כללית. התנועה הנכנסת מוצגת. אחרי שהסקריפט ליצירת תנועה פועל במשך דקה, מוצגים שלושה קווים בתרשים Total latency (האחוזון ה-50, ה-95 וה-98). הנתונים האלה מספקים הערכה של זמני התגובה.

2. מתחת לתרשימים, בקטע קישורים, לוחצים על הצגת יומנים עבור GET/airportName. בדף Logs Explorer מוצגים יומני הבקשות של ה-API.

3. פותחים את Cloud Shell.

   פתיחת Cloud Shell

4. כדי לעצור את הסקריפט, מזינים Control+C.

הוספת מכסה ל-API

בטא

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאי שירות הכלליים" בתנאים הספציפיים של השירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

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

1. ב-Cloud Shell, פורסים את הגדרות נקודות הקצה (Endpoints) שיש להן מכסת שימוש.

./deploy_api.sh ../openapi_with_ratelimit.yaml

After you deploy an updated Endpoints configuration, it
becomes active within a minute.

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

   לדף Credentials

2. לוחצים על Create credentials ואז על API key. מפתח API חדש מוצג במסך.

3. לוחצים על העתקה .

4. ב-Cloud Shell, מקלידים את הפקודה הבאה. מחליפים את YOUR_API_KEY במפתח ה-API שיצרתם.

export API_KEY=YOUR_API_KEY

1. שולחים ל-API בקשה באמצעות מפתח ה-API שנוצר.

./query_api_with_key.sh $API_KEY

The output is similar to the following:

curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

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

./generate_traffic_with_key.sh $API_KEY

1. אחרי שמריצים את הסקריפט למשך 5-10 שניות, מזינים Control+C כדי להפסיק את הסקריפט.

2. שולחים בקשה מאומתת נוספת אל ה-API.

./query_api_with_key.sh $API_KEY

The output is similar to the following:

{
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
    {
    "@type": "type.googleapis.com/google.rpc.DebugInfo",
    "stackEntries": [],
    "detail": "internal"
    }
    ]
}

אם מקבלים תשובה אחרת, מריצים שוב את generate_traffic_with_key.sh הסקריפט ומנסים שוב.

כל הכבוד! הגדרתם בהצלחה הגבלת קצב (rate limiting) ל-API. אפשר גם להגדיר מגבלות שונות לשיטות שונות של API, ליצור כמה סוגים של מכסות ולעקוב אחרי הצרכנים שמשתמשים בממשקי ה-API.

מידע נוסף על מכסות

הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם בדף הזה, פועלים לפי השלבים הבאים:

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

זהירות: כשמוחקים פרויקט:
• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.
1. במסוף Google Cloud , נכנסים לדף Manage resources.

   כניסה לדף Manage resources

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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

• סקירה כללית של Endpoints:

  • מידע על נקודות קצה
  • נקודות קצה: סקירה כללית של הארכיטקטורה

• כדי לקבל מידע על מסגרות ה-API השונות ש-Endpoints תומך בהן:

  • מפרט OpenAPI
  • נקודות קצה של ממשקי gRPC API
  • מידע על מסגרות של נקודות קצה

• כדי ללמוד איך להגדיר ולפרוס API לדוגמה, בוחרים הדרכה לאחת ממסגרות ה-API:

  • נקודות קצה ל-OpenAPI: מדריכים
  • נקודות קצה ל-gRPC: מדריכים
  • Endpoints Frameworks: Tutorials