בדף הזה מוסבר איך להגדיר, לפרוס ולשלוח בקשות ל-API לדוגמה באמצעות Cloud Endpoints Frameworks for Python. Endpoints Frameworks for Python משולב עם סביבת זמן הריצה הרגילה של Python 2.7 ב-App Engine. Endpoints Frameworks כולל כלים, ספריות ויכולות שמאפשרים לכם ליצור ממשקי API וספריות לקוח מאפליקציית App Engine.
מטרות
במהלך העבודה עם המדריך, תוכלו להשתמש ברשימת המשימות הכללית הבאה. כדי לשלוח בקשות ל-API, צריך לבצע את כל המשימות.
- מגדירים Google Cloud פרויקט. לפני שמתחילים
- מתקינים את התוכנה הנדרשת ויוצרים אפליקציית App Engine. מידע נוסף זמין במאמר בנושא התקנה והגדרה של תוכנה נדרשת.
- מורידים את הקוד לדוגמה. קבלת קוד לדוגמה
- ליצור מסמך OpenAPI. איך מגדירים נקודות קצה
- פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
- מריצים את הדוגמה במחשב. איך מריצים את הדוגמה באופן מקומי
- יוצרים קצה עורפי להצגת ה-API ופורסים את ה-API. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
- שליחת בקשה ל-API. שליחת בקשה ל-API
- מעקב אחר פעילות ב-API. מידע נוסף זמין במאמר בנושא מעקב אחר פעילות של API.
- כדי להימנע מחיובים בחשבון Google Cloud , מידע נוסף זמין בקטע הסרת המשאבים.
עלויות
במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:
כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.
כשמסיימים את המשימות שמתוארות במסמך הזה אפשר למחוק את המשאבים שיצרתם כדי להימנע מחיובים נוספים. מידע נוסף זמין בקטע הסרת המשאבים.
לפני שמתחילים
- נכנסים לחשבון 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.
התקנה והגדרה של תוכנה נדרשת
- כדי להגדיר את סביבת הפיתוח של App Engine Standard, פועלים לפי ההוראות שבמאמר התקנת Google Cloud CLI ל-Python. חשוב לוודא שמתקינים את הרכיבים
app-engine-pythonו-app-engine-python-extrasgcloud. - מריצים את הפקודות הבאות:
-
מעדכנים את ה-CLI של gcloud.
gcloud components update
-
מוודאים ש-Google Cloud CLI (
gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:gcloud auth login
- בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.
-
מגדירים את פרויקט ברירת המחדל למזהה הפרויקט.
gcloud config set project [YOUR_PROJECT_ID]
מחליפים את
[YOUR_PROJECT_ID]במזהה הפרויקט ב- Google Cloud. אם יש לכם פרויקטים אחרים Google Cloud ואתם רוצים להשתמש ב-gcloudכדי לנהל אותם, תוכלו לקרוא את המאמר בנושא ניהול ההגדרות האישיות של ה-CLI של gcloud.
-
מעדכנים את ה-CLI של gcloud.
-
אתם צריכים אפליקציה כדי לשלוח בקשות ל-API לדוגמה.
- משתמשי Linux ו-macOS: במדריך הזה יש דוגמה לשימוש ב-
curl, שבדרך כלל מותקן מראש במערכת ההפעלה. אם אין לכם אתcurl, אתם יכולים להוריד אותו מcurlדף ההורדות והגרסאות. - משתמשי Windows: במדריך הזה יש דוגמה לשימוש ב-
Invoke-WebRequest, שנתמך ב-PowerShell 3.0 ואילך.
- משתמשי Linux ו-macOS: במדריך הזה יש דוגמה לשימוש ב-
- מוודאים שסביבת הפיתוח בשפת Python כוללת את pip.
- חשוב לוודא שאפשר לקמפל תוספי C ל-Python.
- Windows: נדרשת גרסה 9.0 ומעלה של Microsoft Visual C++. אפשר להוריד את Microsoft Visual C++ Compiler ל-Python 2.7 ממרכז ההורדות של מיקרוסופט .
- מערכות הפעלה אחרות: בהתאם למערכת ההפעלה, יכול להיות שתצטרכו להתקין כלי קומפילציה (לפעמים בחבילה שנקראת
build-essential) או את כותרות הפיתוח של Python (לפעמים בחבילה שנקראתpython-dev).
-
ב-Linux, מגדירים את משתנה הסביבה
ENDPOINTS_GAE_SDKלנתיב של תיקיית App Engine SDK:[Path-to-Google-Cloud-SDK]/platform/google_appengine.מחליפים את
[Path-to-Google-Cloud-SDK]בפלט של הפקודה הבאה:gcloud info --format="value(installation.sdk_root)"
- יוצרים אפליקציית App Engine:
- בוחרים את האזור שבו רוצים ליצור את אפליקציית App Engine. כדי לקבל רשימה של אזורים, מריצים את הפקודה הבאה:
gcloud app regions list
- יוצרים אפליקציית App Engine באמצעות הפקודה הבאה.
מחליפים את
[YOUR_PROJECT_ID]במזהה הפרויקט ב- Google Cloudואת[YOUR_REGION]באזור שבו רוצים ליצור את אפליקציית App Engine.gcloud app create \ --project=[YOUR_PROJECT_ID] \ --region=[YOUR_REGION]
לדוגמה:
gcloud app create --project=example-project-12345 --region=us-central
- בוחרים את האזור שבו רוצים ליצור את אפליקציית App Engine. כדי לקבל רשימה של אזורים, מריצים את הפקודה הבאה:
קבלת הקוד לדוגמה
כדי לשכפל את ה-API לדוגמה מ-GitHub:
משכפלים את המאגר לדוגמה ומעבירים אותו למכונה המקומית:
git clone https://github.com/GoogleCloudPlatform/python-docs-samplesעוברים לספרייה שמכילה את הקוד לדוגמה:
cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
הגדרת נקודות קצה
כדי להגדיר Endpoints, צריך קודם להתקין את ספריית Python של Endpoints Frameworks. לאחר מכן משתמשים בכלי מספריית Endpoints Frameworks כדי ליצור מסמך OpenAPI עבור ה-API לדוגמה. כדי שמערכת Endpoints תוכל לנהל את ה-API, צריך את ספריית Endpoints Frameworks ואת מסמך OpenAPI. מידע נוסף זמין במאמר בנושא הוספת ניהול API.
התקנה של ספריית Endpoints Frameworks
בקטע הזה מוסבר איך להשתמש ב-pip של Python כדי להוסיף את ספריית Endpoints Frameworks לספריית הפרויקט של ה-API לדוגמה.
כדי להוסיף את ספריית Endpoints Frameworks לדוגמה:
מוודאים שאתם בספרייה הראשית של ה-API לדוגמה,
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.יוצרים ספריית משנה
/libבפרויקט:mkdir libמהספרייה הראשית לדוגמה
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, מריצים את פקודת ההתקנה:pip install --target lib --requirement requirements.txt --ignore-installedשימו לב לנקודות הבאות:
יכול להיות שהפקודה
pipתשתמש ב-GNU Compiler Collection (GCC) כדי לקמפל מודולים של תוספים. אם אתם משתמשים ב-macOS וזו הפעם הראשונה שאתם מריצים את GCC במערכת, יכול להיות שתצטרכו לאשר את הרישיון של Apple ל-XCode. כדי לעשות זאת, מריצים אתsudo xcodebuild -license.אם מותקנות במחשב כמה גרסאות של Python, צריך לוודא שמשתמשים בגרסה של
pipשמתאימה לגרסת Python שבה משתמשים במדריך הזה. אי התאמה בין גרסאות (לדוגמה,pipמ-Python 3.4 בזמן השימוש ב-pythonמ-Python 2.7) עלולה לגרום לשגיאות שקשה להבין. במקרה הצורך, אפשר להריץ את pip כמודול Python: מחליפים אתpipבפקודה הקודמת ב-python -m pip.אם
pipלא מצליח למצוא חבילה מתאימה כשמריצים את הפקודה, נסו לשדרג אותה על ידי הרצתpip install --upgrade pip. אחרי שהשדרוג יסתיים, נסו להריץ שוב את פקודת ההתקנה.במהדורות מסוימות של Debian ו-Ubuntu, יכול להיות שהפקודה
pipתיכשל עם השגיאה DistutilsOptionError. אם השגיאה הזו מוצגת, צריך להוסיף את הדגל --system.
אחרי שהתהליך יסתיים בהצלחה, הספרייה lib תאוכלס בקבצים שנדרשים לבניית האפליקציה של Endpoints Frameworks.
יצירת מסמך OpenAPI
משתמשים בכלי מספריית Endpoints Frameworks כדי ליצור מסמך שמתאר את ה-API בארכיטקטורת REST של קוד הדוגמה.
כדי ליצור את מסמך OpenAPI:
מוודאים שאתם נמצאים בספרייה הראשית לדוגמה:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echoיוצרים את מסמך OpenAPI:
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.comמחליפים את
[YOUR_PROJECT_ID]במזהה הפרויקט ב- Google Cloud . מתעלמים מהאזהרות שמוצגות. הכלי Endpoints יוצר מסמך OpenAPI בשםechov1openapi.jsonבספרייה הנוכחית. הכלי Endpoints נותן לקובץ שם על סמך השם והגרסה של השירות שצוינו ב-decorator@endpoints.api. מידע נוסף זמין במאמר בנושא יצירת ה-API.Endpoints משתמש בטקסט שצוין בארגומנט
hostnameכשם השירות. פורמט השםYOUR_PROJECT_ID.appspot.comתואם לרשומת ה-DNS שנוצרת אוטומטית כשפורסים את ה-API בחלק האחורי של App Engine. לכן במקרה הזה, שם השירות של Endpoints ושם הדומיין שמוגדר במלואו (FQDN) זהים.
בסיום מוצלח, מוצגת ההודעה הבאה:
OpenAPI spec written to ./echov1openapi.json
פריסת ההגדרה של נקודות הקצה
כדי לפרוס את ההגדרה של Endpoints, משתמשים ב-Service Infrastructure, פלטפורמת השירותים הבסיסית של Google, שמשמשת את Endpoints ושירותים אחרים ליצירה ולניהול של ממשקי API ושירותים.
כדי לפרוס את קובץ התצורה:
- מוודאים שאתם נמצאים בספרייה הראשית של הדוגמה:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
- מריצים את הפקודה הבאה כדי לפרוס את מסמך ה-OpenAPI שנוצר בקטע הקודם:
gcloud endpoints services deploy echov1openapi.json
כך נוצר שירות Endpoints חדש עם השם שציינתם בארגומנט
hostnameכשמריצים את כלי Endpoints כדי ליצור את מסמך OpenAPI. לא משנה מה שם שירות ה-Endpoints, כשפורסים את ה-API ב-App Engine, נוצרת רשומת DNS בפורמט השםYOUR_PROJECT_ID.appspot.com, שהוא ה-FQDN שבו משתמשים כששולחים בקשות ל-API.במהלך היצירה וההגדרה של השירות, Service Management מציג הרבה מידע במסוף. אפשר להתעלם מהאזהרות לגבי הנתיבים ב-
echov1openapi.jsonשלא דורשים מפתח API. בסיום הפריסה, תוצג הודעה דומה לזו:Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
בדוגמה הקודמת,
2017-02-13-r2הוא מזהה הגדרות השירות ו-example-project-12345.appspot.comהוא שם השירות.מידע נוסף מופיע ב
gcloud endpoints services deployבמאמרי העזרה שלgcloud.
בדיקת השירותים הנדרשים
כדי לספק ניהול API, Endpoints Frameworks דורש את השירותים הבאים:| שם | כותרת |
|---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
ברוב המקרים, הפקודה gcloud endpoints services deploy מפעילה את השירותים הנדרשים האלה. עם זאת, הפקודה gcloud מסתיימת בהצלחה אבל לא מפעילה את השירותים הנדרשים בנסיבות הבאות:
אם השתמשתם באפליקציה של צד שלישי כמו Terraform ולא כללתם את השירותים האלה.
הפריסה של הגדרת ה-Endpoints בוצעה בפרויקטGoogle Cloud קיים שבו השירותים האלה הושבתו באופן מפורש.
כדי לוודא שהשירותים הנדרשים מופעלים, משתמשים בפקודה הבאה:
gcloud services list
אם השירותים הנדרשים לא מופיעים ברשימה, צריך להפעיל אותם:
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.comצריך גם להפעיל את שירות Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
כדי לדעת מהו ENDPOINTS_SERVICE_NAME, אפשר:
אחרי פריסת ההגדרה של Endpoints, נכנסים לדף Endpoints במסוף Cloud. רשימת האפשרויות האפשריות של ENDPOINTS_SERVICE_NAME מוצגת בעמודה שם השירות.
ב-OpenAPI, ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה
hostבמפרט OpenAPI. ב-gRPC, ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדהnameבהגדרות של נקודות הקצה של gRPC.
מידע נוסף על פקודות gcloud זמין במאמר שירותי gcloud.
הרצת הדוגמה באופן מקומי
אחרי פריסת ההגדרה של Endpoints, אפשר להריץ את הדוגמה באופן מקומי באמצעות שרת הפיתוח המקומי.
מוודאים שאתם נמצאים בספרייה הראשית לדוגמה:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echoמפעילים את שרת הפיתוח המקומי:
dev_appserver.py ./app.yamlכברירת מחדל, שרת הפיתוח מאזין בכתובת
http://localhost:8080, כפי שמצוין ביומני המסוף שמודפסים על ידיdev_appserver.py: Google CloudINFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080שליחת בקשה לשרת הפיתוח המקומי:
Linux או Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
במהלך curl הקודמים:
- האפשרות
--dataמציינת את הנתונים שיישלחו ל-API. - האפשרות
--headerמציינת שהנתונים הם בפורמט JSON.
PowerShell
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").Content
בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.
ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:
{
"message": "hello world"
}
פריסת ה-API backend
עד עכשיו פרסתם את מסמך ה-OpenAPI ב-Service Management, אבל עדיין לא פרסתם את הקוד שמפעיל את ה-backend של ה-API. בקטע הזה מוסבר איך פורסים את ה-API לדוגמה ב-App Engine.
כדי לפרוס את העורף של ה-API:
- מריצים את הפקודה הבאה כדי להציג את מזהה תצורת השירות:
gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
מחליפים את
[YOUR_PROJECT_ID]במזהה הפרויקט. לדוגמה:gcloud endpoints configs list --service=example-project-12345.appspot.com
- Open the
app.yamlfile in thepython-docs-samples/appengine/standard/endpoints-frameworks-v2/echodirectory. - מבצעים את השינויים הבאים בקטע
env_variables:- בשדה
ENDPOINTS_SERVICE_NAME, מחליפים אתYOUR-PROJECT-IDבמזהה הפרויקט Google Cloud . - בשדה
ENDPOINTS_SERVICE_VERSION, מחליפים את הטקסט במזהה של הגדרת השירות. לדוגמה:
ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
- בשדה
- מריצים את הפקודה הבאה:
gcloud app deploy
- פועלים לפי ההוראות שמוצגות במסך. ממתינים כמה רגעים עד שהפריסה תצליח, ומתעלמים מהודעות האזהרה. בסיום הפריסה, תוצג הודעה דומה לזו:
File upload done. Updating service [default]...done.
אם קיבלתם הודעת שגיאה, תוכלו להיעזר בקטע פתרון בעיות במסמכי App Engine.
מומלץ להמתין כמה דקות לפני שליחת בקשות ל-API בזמן שהאפליקציה עוברת אתחול מלא ב-App Engine.
- האפשרות
--dataמציינת את הנתונים שיישלחו ל-API. - האפשרות
--headerמציינת שהנתונים הם בפורמט JSON. - בוחרים באפשרות
POSTכפועל ה-HTTP. - בכותרת, בוחרים את המפתח
content-typeואת הערךapplication/json. - בגוף ההודעה, מזינים את הפרטים הבאים:
{"message":"hello world"} -
מזינים את כתובת ה-URL של האפליקציה לדוגמה. לדוגמה:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo אפשר לראות את הגרפים של הפעילות ב-API במסוף Google Cloud בדף Endpoints > Service.
יכול להיות שיחלפו כמה רגעים עד שהבקשה תשתקף בתרשימים.
מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.
שליחת בקשה ל-API לדוגמה
Linux או Mac OS
שליחת בקשת HTTP באמצעות curl. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב-Google Cloud :
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
במהלך curl הקודמים:
PowerShell
שליחת בקשת HTTP באמצעות Invoke-WebRequest. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloud :
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.
אפליקציה של צד שלישי
אפשר להשתמש באפליקציה של צד שלישי, כמו התוסף Postman לדפדפן Chrome, כדי לשלוח את הבקשה:
ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:
{
"message": "hello world"
}
אם לא קיבלתם תגובה, אפשר להיעזר במאמר בנושא פתרון בעיות שקשורות לתגובות.
מעקב אחר פעילות ב-API
הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים בנפרד.
- במסוף Google Cloud , נכנסים לדף Manage resources.
- ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
המאמרים הבאים
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2026-06-18 (שעון UTC).