Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מעצבי פנים

ה-Frameworks של Cloud Endpoints ל-Python decorators מתארים את הגדרת ה-API, השיטות, הפרמטרים ופרטים חיוניים אחרים שמגדירים את המאפיינים וההתנהגות של נקודת הקצה.

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

הגדרת ה-API ‏ (`@endpoints.api`)

אפשר לספק כמה ארגומנטים ל-@endpoints.api כדי להגדיר את ה-API. בטבלה הבאה מתוארים הארגומנטים הזמינים:

ארגומנטים של ‎@endpoints.api	תיאור	דוגמה
`allowed_client_ids`	חובה אם ה-API שלכם משתמש באימות. רשימה של מזהי לקוחות שמורשים לבקש טוקנים. מידע נוסף זמין במאמר בנושא מזהי לקוח וקהלים מורשים.	`allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID`]
`api_key_required`	זה שינוי אופציונלי. ההגבלה הזו משמשת להגבלת הגישה לבקשות שכוללות מפתח API.	`api_key_required=True`
`audiences`	חובה אם ה-API דורש אימות ואם אתם תומכים בלקוחות Android. עבור אסימוני מזהה Google, יכולה להיות כאן רשימה של מזהי לקוח שעבורם מתבצעת בקשה לאסימונים. אם האסימונים מונפקים על ידי ספקי אימות של צד שלישי, כמו Auth0, צריך להגדיר מילון שממפה בין שמות של מנפיקי אימות לבין רשימות של קהלים. מידע נוסף זמין במאמר בנושא מזהי לקוח וקהלים מורשים.	`audiences=['1-web-apps.apps.googleusercontent.com']` או `audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]}`
`base_path`	זה שינוי אופציונלי. המאפיין הזה משמש להצגת ה-API מהנתיב שצוין. אם מציינים את הארגומנט הזה, צריך לשנות גם את הקטע `handlers` בקובץ `app.yaml`.	מידע נוסף מופיע במאמר בנושא הצגת ה-API מנתיב אחר.
`canonical_name`	זה שינוי אופציונלי. המאפיין הזה משמש לציון שם אחר או קריא יותר ל-API בספריית הלקוח. השם הזה משמש ליצירת שמות בספריית הלקוח. ה-API של ה-Backend ממשיך להשתמש בערך שצוין במאפיין `name`. לדוגמה, אם במאפיין `name` של ה-API מוגדר הערך dfaanalytics, אפשר להשתמש במאפיין הזה כדי לציין שם קנוני של DFA Group Analytics. לאחר מכן, המחלקות של הלקוח שנוצרות יכללו את השם `DfaGroupAnalytics`. צריך לכלול את הרווחים הרלוונטיים בין השמות כמו שמוצג. הרווחים האלה מוחלפים בסימון camel case או בקו תחתון.	`canonical_name='DFA Analytics'`
`description`	תיאור קצר של ה-API. הוא נחשף בשירות הגילוי כדי לתאר את ה-API, ויכול לשמש גם ליצירת תיעוד, כפי שמתואר במאמר יצירת ספריות לקוח.	`description='Sample API for a simple game'`
`documentation`	זה שינוי אופציונלי. כתובת ה-URL שבה המשתמשים יכולים למצוא תיעוד לגבי הגרסה הזו של ה-API. המידע הזה מוצג ב-API Explorer בקטע 'מידע נוסף' בחלק העליון של הדף, כדי שהמשתמשים יוכלו לקבל מידע על השירות שלכם.	`documentation='http://link_to/docs'`
`hostname`	שם המארח של אפליקציית App Engine. כלי שורת הפקודה של Endpoints Frameworks משתמש בערך שאתם מציינים כאן כשהוא יוצר מסמך Discovery או מסמך OpenAPI. אם לא מציינים כאן את שם המארח, צריך לציין את שם המארח בשדה `application` בקובץ `app.yaml` או לציין את מזהה הפרויקט כשפורסים את אפליקציית App Engine.	`hostname='your_app_id.appspot.com'`
`issuers`	זה שינוי אופציונלי. הגדרות מותאמות אישית של מנפיק JWT. זה צריך להיות מיפוי מילוני משמות של מנפיקים לאובייקטים מסוג `endpoints.Issuer`.	`issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")}`
`name`	חובה. שם ה-API, שמשמש כקידומת לכל ה-methods והנתיבים של ה-API. הערך של `name`: חייב להתחיל באות קטנה. חייב להתאים לביטוי הרגולרי `[a-z]+[A-Za-z0-9]`. כלומר, שאר השם יכול לכלול אותיות רישיות וקטנות או מספרים. כדי לפרוס כמה ממשקי API כחלק משירות יחיד, כל שמות ה-API צריכים להתאים לביטוי הרגולרי `[a-z][a-z0-9]{0,39}`. כלומר, השם צריך להתחיל באות קטנה, שאר התווים צריכים להיות אותיות קטנות או מספרים, והאורך המקסימלי הוא 40 תווים.	`name='yourApi'` או `name='yourapi'`
`limit_definitions`	זה שינוי אופציונלי. משמש להגדרת מכסות ל-API. מידע נוסף זמין במאמר limit_definitions.
`owner_domain`	זה שינוי אופציונלי. שם הדומיין של הישות שבבעלותה ה-API. הפרמטר הזה משמש יחד עם `owner_name` כדי לספק רמזים לשם הנכון של ספריית הלקוח כשיוצרים אותה עבור ה-API הזה. (נתיב החבילה הוא ההיפוך של `owner_domain` ושל `package_path` אם הם סופקו. ברירת המחדל היא שימוש ב-`appid.apppost.com`	`owner_domain='your-company.com'`
`owner_name`	זה שינוי אופציונלי. השם של הישות שבבעלותה ה-API. הפרמטר הזה משמש יחד עם `owner_domain` כדי לספק רמזים לשם הנכון של ספריית הלקוח כשיוצרים אותה עבור ה-API הזה.	`owner_name='Your-Company'`
`package_path`	זה שינוי אופציונלי. הפרמטר הזה משמש להגדרת היקף נוסף ל'חבילה' שאליה ה-API הזה שייך, והערכים מופרדים באמצעות `/` כדי לציין קיבוצים לוגיים של ממשקי API. לדוגמה, אם מציינים `cloud/platform`, נתיב ספריית הלקוח מוגדר כ-`cloud/platform/<ApiName>` וחבילת ספריית הלקוח מוגדרת כ-`cloud.plaform.<ApiName>`.	`package_path='cloud/platform'`
`scopes`	אם לא מספקים את הפרמטר הזה, ברירת המחדל היא היקף האימייל (`https://www.googleapis.com/auth/userinfo.email`), שנדרש ל-OAuth. אם רוצים, אפשר לעקוף את ההגדרה הזו כדי לציין עוד היקפי הרשאות OAuth 2.0. אפשר גם לבטל את ההיקפים שצוינו כאן לשיטת API מסוימת על ידי ציון היקפים שונים בקישוט `@endpoints.method`. עם זאת, אם מגדירים יותר מהיקף אחד, חשוב לדעת שבדיקת ההיקף עוברת אם האסימון נוצר עבור אחד מההיקפים שצוינו. כדי לדרוש כמה היקפי הרשאה, מציינים מחרוזת אחת עם רווח בין כל היקף הרשאה.	`scopes=['ss0', 'ss1 and_ss2']`
`title`	זה שינוי אופציונלי. הטקסט שמוצג ב-API Explorer ככותרת של ה-API, ומוצג בשירותי הגילוי והספרייה.	`title='My Backend API'`
`version`	חובה. מציינים את הגרסה של Cloud Endpoints. הערך הזה מופיע בנתיב של ה-API. אם מציינים מחרוזת גרסה שתואמת לתקן SemVer, רק מספר הגרסה הראשית מופיע בנתיב של ה-API כשפורסים אותו. לדוגמה, ל-API בשם `echo` עם גרסה `2.1.0` יהיה נתיב שדומה ל-`/echo/v2`. אם מעדכנים את API‏ `echo` לגרסה `2.2.0` ומפעילים שינוי שתואם לגרסאות קודמות, הנתיב נשאר `/echo/v2`. כך תוכלו לעדכן את מספר גרסת ה-API כשאתם מבצעים שינוי שתואם לגרסאות קודמות, בלי לשבור נתיבים קיימים עבור הלקוחות שלכם. אבל אם מעדכנים את `echo` API לגרסה `3.0.0` (כי פורסים שינוי שעלול לשבור את התאימות), הנתיב משתנה ל-`/echo/v3`.	`version='v1'` או `version='2.1.0'`

`limit_definitions`

כדי להגדיר מכסות לממשק ה-API, מציינים את הארגומנט האופציונלי limit_definitions ל-@endpoints.api. כדי להגדיר מכסה, צריך גם:

מתקינים את גרסה 2.4.5 ואילך של ספריית Endpoints Frameworks.
מוסיפים את הארגומנט metric_costs למעצב השיטה של כל שיטה שרוצים להחיל עליה מכסת שימוש.

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

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

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

לכל מופע של LimitDefinition צריכים להיות הערכים הבאים:

רכיב	תיאור
name	השם של מונה בקשות ה-API. בדרך כלל, זהו סוג הבקשה (למשל, 'בקשות קריאה' או 'בקשות כתיבה') שמזהה באופן ייחודי את המכסה.
השם המוצג	הטקסט שמוצג לזיהוי המכסה בכרטיסייה Quotas בדף Endpoints > Services. הטקסט הזה מוצג גם לצרכני ה-API שלכם בדף Quotas בקטע IAM & admin ובקטע API & Services. השם המוצג יכול לכלול עד 40 תווים. כדי שהשם יהיה קריא, הטקסט 'per minute per project' מצורף אוטומטית לשם התצוגה בדפי המכסות. כדי לשמור על עקביות עם השמות המוצגים של שירותי Google שמופיעים בדפי המכסות שצרכני ה-API שלכם רואים, אנחנו ממליצים על הדברים הבאים לגבי השם המוצג: משתמשים באפשרות 'בקשות' כשיש רק מדד אחד. אם יש לכם כמה מדדים, כל אחד מהם צריך לתאר את סוג הבקשה ולכלול את המילה requests (בקשות) (למשל Read requests (בקשות קריאה) או Write requests (בקשות כתיבה)). אם אחד מהעלויות של המכסה הזו גדול מ-1, צריך להשתמש ב'יחידות מכסה' במקום ב'בקשות'.
הגבלה	ערך מספרי של מספר הבקשות המקסימלי בדקה לכל פרויקט צרכן במכסה.

רכיב

תיאור

name

השם של מונה בקשות ה-API. בדרך כלל, זהו סוג הבקשה (למשל, 'בקשות קריאה' או 'בקשות כתיבה') שמזהה באופן ייחודי את המכסה.

השם המוצג

הטקסט שמוצג לזיהוי המכסה בכרטיסייה Quotas בדף Endpoints > Services. הטקסט הזה מוצג גם לצרכני ה-API שלכם בדף Quotas בקטע IAM & admin ובקטע API & Services. השם המוצג יכול לכלול עד 40 תווים.

כדי שהשם יהיה קריא, הטקסט 'per minute per project' מצורף אוטומטית לשם התצוגה בדפי המכסות. כדי לשמור על עקביות עם השמות המוצגים של שירותי Google שמופיעים בדפי המכסות שצרכני ה-API שלכם רואים, אנחנו ממליצים על הדברים הבאים לגבי השם המוצג:

משתמשים באפשרות 'בקשות' כשיש רק מדד אחד.
אם יש לכם כמה מדדים, כל אחד מהם צריך לתאר את סוג הבקשה ולכלול את המילה requests (בקשות) (למשל Read requests (בקשות קריאה) או Write requests (בקשות כתיבה)).
אם אחד מהעלויות של המכסה הזו גדול מ-1, צריך להשתמש ב'יחידות מכסה' במקום ב'בקשות'.

הגבלה

ערך מספרי של מספר הבקשות המקסימלי בדקה לכל פרויקט צרכן במכסה.

דוגמה

quota_limits = [
  endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),
  endpoints.LimitDefinition('list-requests', 'List Requests', 100),
  endpoints.LimitDefinition('write-requests', 'Write Requests', 50)
]

@endpoints.api(name='bookstore',
               version='v1',
               limit_definitions=quota_limits)

מזהי לקוחות וקהלים מותרים

באימות OAuth2, טוקן OAuth2 מונפק למזהה לקוח ספציפי, מה שאומר שאפשר להשתמש במזהה הלקוח הזה כדי להגביל את הגישה לממשקי ה-API שלכם. כשרושמים אפליקציות ל-Android ב Google Cloud מסוף, נוצר עבורן מזהה לקוח. מזהה הלקוח הזה הוא זה שמבקש טוקן OAuth2 מ-Google למטרות אימות. כשממשק ה-API של ה-backend מוגן על ידי אימות, נשלח אסימון גישה ב-OAuth2 והוא נפתח על ידי Endpoints Frameworks for App Engine. מזהה הלקוח מחולץ מהאסימון, ואז המזהה מושווה לרשימת מזהי הלקוחות המקובלים שהוגדרו ב-backend (הרשימה allowed_client_ids).

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

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

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

מידע על קהלים

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

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

מנפיק טוקנים לאימות של צד שלישי

אם האפליקציה שלכם מקבלת אסימוני אימות שהם לא אסימוני Google ID ומונפקים על ידי מנפיקים של צד שלישי, אתם צריכים להגדיר בצורה נכונה את הארגומנטים audiences ו-issuers ב-@endpoints.api כדי לספק את המידע על המנפיקים של צד שלישי. לדוגמה:

@endpoints.api(
        audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
        issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
                                           'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):

הגדרת שיטה של API ‏ (`@endpoints.method`)

אפשר להגדיר את ההגדרות audiences, scopes ו-allowed_client_ids לכל ה-API באמצעות @endpoints.api, או להגדיר אותן לשיטה באמצעות @endpoints.method. אם ההגדרות האלה מצוינות גם ב-API וגם ברמת השיטה, ההגדרה של השיטה מבטלת את ההגדרה של ה-API.

כדי ליצור שיטה ב-API, מעטרים את שיטת Python המתאימה באמצעות @endpoints.method, ומספקים ארגומנטים להגדרת השימוש בשיטה. לדוגמה, אתם מציינים באילו מחלקות של בקשות ותגובות Message צריך להשתמש.

הארגומנטים הזמינים מפורטים בטבלה הבאה:

`@endpoints.method` ארגומנטים	תיאור	דוגמה
`allowed_client_ids`	ההגדרה הזו מבטלת את המאפיין המקביל שצוין ב-`@endpoints.api`. מידע נוסף זמין במאמר בנושא מזהי לקוח וקהלים מורשים.	`['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com']`
`api_key_required`	זה שינוי אופציונלי. ההגבלה הזו משמשת להגבלת הגישה לבקשות שכוללות מפתח API.	`api_key_required=True`
`audiences`	מחליף את הארגומנט המקביל שצוין ב-`@endpoints.api`. מידע נוסף זמין במאמר בנושא מזהי לקוח וקהלים מורשים.	`['1-web-apps.apps.googleusercontent.com']`
`metric_costs`	זה שינוי אופציונלי. השדה מציין שלשיטה יש הגבלת מכסה. זהו מילון עם צמדי המפתח:ערך הבאים: ‫name: שם שציינתם בארגומנט limit_definitions של ה-API decorator. cost: מספר שלם שמציין את העלות של כל בקשה. העלות מאפשרת לשיטות לצרוך בשיעורים שונים מאותה מכסה. לדוגמה, אם למכסה יש מגבלה של 1,000 ועלות של 1, האפליקציה שקוראת ל-API יכולה לשלוח 1,000 בקשות בדקה לפני שהיא חורגת מהמגבלה. אם העלות היא 2 לאותה מכסת שימוש, אפליקציית שיחות יכולה לשלוח רק 500 בקשות בדקה לפני שהיא חורגת מהמגבלה.	`metric_costs={'read-requests': 1}`
`http_method`	שיטת ה-HTTP שבה רוצים להשתמש. אם לא מגדירים את המדיניות הזו, המערכת משתמשת ב-`'POST'` כברירת מחדל.	`'GET'`
`name`	שם חלופי לשיטה הזו. הערך של `name`: חייב להתחיל באות קטנה. חייב להתאים לביטוי הרגולרי `[a-z]+[A-Za-z0-9]*`.	`'yourApi'`
`path`	נתיב ה-URI לגישה לשיטה הזו. אם לא מגדירים את זה, המערכת משתמשת בשם של שיטת Python. אם אתם מתכננים להוסיף ניהול API, אל תכללו לוכסן בסוף הנתיב.	`'yourapi/path'`
`Request Message` כיתה	המחלקות Google Protocol RPC `Request Message` שבהן יש להשתמש בקריאה לשיטה. אפשרות אחרת היא לציין את שם הכיתה.	`YourRequestClass`
`Response Message` כיתה	המחלקות Google Protocol RPC `Response Message` שבהן יש להשתמש בקריאה לשיטה. אפשרות אחרת היא לציין את שם הכיתה.	`YourResponseClass`

שימוש ב-`ResourceContainer` עבור ארגומנטים של נתיב או מחרוזת שאילתה

אם הבקשה מכילה ארגומנטים של נתיב או של מחרוזת שאילתה, אי אפשר להשתמש במחלקה פשוטה Message כמו שמתואר במאמר יצירת ה-API. במקום זאת, צריך להשתמש במחלקה ResourceContainer באופן הבא:

מגדירים מחלקה Message עם כל הארגומנטים שמועברים בגוף הבקשה. אם אין ארגומנטים בגוף הבקשה, לא צריך להגדיר מחלקה Message: פשוט משתמשים ב-message_types.VoidMessage. לדוגמה:
```
class Greeting(messages.Message):
    """Greeting that stores a message."""

    message = messages.StringField(1)
```
מגדירים ResourceContainer עם המחלקה Message שהגדרתם בשלב הקודם כפרמטר הראשון. בפרמטרים הבאים מציינים את הארגומנטים של נתיב ומחרוזת השאילתה. לדוגמה:
```
MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
```
כאשר הארגומנט הראשון הוא המחלקה Message של הנתונים בגוף הבקשה, ו-times הוא מספר שצפוי בנתיב או במחרוזת השאילתה שמצורפים לבקשה.

מספקים את ResourceContainer ל-method שמטפל בבקשה, בפרמטר הראשון, ומחליפים את מחלקת הבקשה Message שאחרת הייתה מסופקת במיקום הזה. בקטע הקוד הבא אפשר לראות את ResourceContainer ואת endpoints.method:

# This ResourceContainer is similar to the one used for get_greeting, but
# this one also contains a request body in the form of a Greeting message.
MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
)

@endpoints.method(
    # This method accepts a request body containing a Greeting message
    # and a URL parameter specifying how many times to multiply the
    # message.
    MULTIPLY_RESOURCE,
    # This method returns a Greeting message.
    Greeting,
    path="greetings/multiply/{times}",
    http_method="POST",
    name="greetings.multiply",
)
def multiply_greeting(self, request):
    return Greeting(message=request.message * request.times)

מוסיפים את הפרמטר path כמו שמוצג, כדי לכלול את ה-API.
אם ל-ResourceContainer יש ארגומנט חובה, בקשת לקוח צריכה לכלול אותו במחרוזת שאילתה (לדוגמה, yourApi?times=2) או בנתיב כתובת ה-URL (לדוגמה, yourApi/2). עם זאת, כדי שממשק ה-API יקבל ערך של ארגומנט באמצעות נתיב כתובת ה-URL, צריך גם להוסיף את שם הארגומנט לנתיב ה-API, כמו שמוצג לארגומנט {times} ב-path='yourApi/{times}.

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

הגדרת ה-API ‏ (@endpoints.api)

limit_definitions