הגדרת Cloud Endpoints

בדף הזה מוסבר על קובצי ההגדרות שנדרשים כדי ליצור שירות gRPC שמנוהל על ידי Endpoints.

דרישות מוקדמות

כנקודת התחלה, בדף הזה מניחים שיש לכם:

בחירת שם השירות

‫Cloud Endpoints משתמש בשם שהגדרתם בקובץ ה-YAML של הגדרת ה-API של gRPC כשם השירות.

השם של שירות ה-API חייב להיות ייחודי ב- Google Cloud. מכיוון ש-Endpoints משתמש בשמות שתואמים ל-DNS כדי לזהות שירותים, מומלץ להשתמש בשם הדומיין או בשם תת-הדומיין של ה-API כשם השירות. בגישה הזו, שם השירות שמופיע בדף Endpoints Services זהה לשם שמשמש בבקשות ל-API. יש ב-Endpoints את הדרישות הבאות לשם השירות:

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

אתם יכולים לרשום דומיין מותאם אישית משלכם (למשל example.com), או להשתמש בדומיין שמנוהל על ידי Google.

שימוש בדומיין שמנוהל על ידי Google

‫Google היא הבעלים של הדומיין cloud.goog והיא מנהלת אותו. אם רוצים להשתמש בדומיין שמנוהל על ידי Google, צריך להשתמש במזהה הפרויקט כחלק משם השירות. Google Cloud מכיוון שלפרויקטים יש מזהה פרויקט ייחודי גלובלי, הדרישה הזו מבטיחה שיהיה לכם שם שירות ייחודי. Google Cloud אם רוצים להשתמש בדומיין cloud.goog, שם השירות צריך להיות בפורמט הבא, כאשר YOUR_API_NAME הוא שם ה-API ו-YOUR_PROJECT_ID הוא מזהה הפרויקטGoogle Cloud :

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

כדי להשתמש בדומיין הזה כשם הדומיין של ה-API, כדאי לקרוא את המאמר בנושא הגדרת DNS בדומיין cloud.goog.

שימוש בדומיין מותאם אישית

אם אתם לא רוצים להשתמש בדומיין שמנוהל על ידי Google, אתם יכולים להשתמש בדומיין מותאם אישית (לדוגמה, myapi.mycompany.com) שיש לכם הרשאה להשתמש בו. לפני שמפעילים את הגדרת ה-API, צריך לפעול לפי השלבים במאמר אימות הבעלות על הדומיין.

הגדרת מאגר אחסון לפרוטוקולים

  1. יוצרים קובץ .proto לשירות. פרטים נוספים זמינים במדריך למפתחים
    .

  2. קומפילציה של מאגרי פרוטוקולים באמצעות קומפיילר protoc בשפה הרלוונטית. לדוגמה:

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  bookstore.proto

    בפקודה הקודמת, --proto_path מוגדר לספריית העבודה הנוכחית. בסביבת ה-build של gRPC, אם אתם משתמשים בספרייה אחרת לקובצי קלט של .proto, צריך לשנות את --proto_path כדי שהקומפיילר יחפש בספרייה שבה שמרתם את קובץ .proto.

    אם הפקודה protoc ליצירת קובץ המתאר נכשלת, צריך לוודא ש:

    • הגרסה של protoc מעודכנת.
    • ציינתם את --proto_path או את הצורה המקוצרת שלו -I לספריות הבסיס של קובצי .proto שיובאו. מידע נוסף זמין בתיעוד של protocol buffers.
    • ציינת --include_imports.

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

הגדרת קובץ הגדרות השירות של gRPC

צריך ליצור קובץ YAML של הגדרות שירות gRPC. בקובץ הזה מציינים את שם השירות והגבלות השימוש, כמו הדרישה למפתח API. אפשר להשתמש בקובץ api_config.yaml מהדוגמה של חנות הספרים כמודל.

  1. שמירת עותק של api_config.yaml.

  2. מזינים את שם השירות בשדה name. לדוגמה:

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. מזינים את הכותרת שמוצגת בדף Endpoints > Services במסוף Google Cloud . לדוגמה:

    title: Bookstore gRPC API

  4. מזינים את שם ה-API בשדה apis:name. הטקסט שאתם מזינים צריך להיות זהה בדיוק לשם ה-API המלא מקובץ .proto. לדוגמה:

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. מגדירים את שאר הקובץ. לדוגמה:

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    מידע נוסף זמין במאמר בנושא כללים ובוררים.

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

דוגמאות נוספות ל-gRPC