יצירת מחבר בהתאמה אישית

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

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

  1. יצירת מחבר בהתאמה אישית – במשימה הזו תגדירו את החוזה בין Integration Connectors לבין נקודת הקצה (הקצה העורפי) על ידי ציון מפרט OpenAPI של נקודת הקצה. בשלב הזה, יש תמיכה רק בגרסה 3.0 של OpenAPI ובכל הגרסאות המשניות שלה. הגדרת המפרט היא פעולה חד-פעמית.
  2. יצירת חיבור של מחבר בהתאמה אישית – במשימה הזו תגדירו את פרטי החיבור של ה-Backend, כמו שם המארח והאימות. לכל מחבר מותאם אישית ספציפי, אפשר ליצור כמה חיבורים שרוצים.

כדי להבין את ההבדל בין מחבר לבין חיבור, אפשר לעיין במאמר מחבר לעומת חיבור.

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

יצירת מחבר בהתאמה אישית

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

  • קישוריות ישירה לנקודת הקצה הציבורית של ה-Backend.
  • קישוריות עקיפה לשרת העורפי דרך נקודת קצה ציבורית מתווכת.

השלבים ליצירת מחבר מותאם אישית משתנים מעט בין שני הדפוסים האלה.

יצירה באמצעות קישוריות ישירה

כדי ליצור מחבר בהתאמה אישית עם קישוריות ישירה לנקודת הקצה של ה-Backend, מבצעים את השלבים הבאים:

המסוף

  1. במסוף, עוברים לדף Integration Connectors > Custom connectors, ואז בוחרים או יוצרים פרויקט ב- Google Cloud .

    מעבר לדף Custom connectors

  2. לוחצים על יצירת חדש כדי לפתוח את הדף יצירת מחבר בהתאמה אישית.
  3. בקטע פרטי מחבר, מגדירים את השדות הבאים:
    1. שם המחבר: מזינים שם למחבר.
    2. השם המוצג: מזינים שם מוצג למחבר.
    3. תיאור: מזינים תיאור.
    4. חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
    5. לוגו: מעלים את התמונה לקטגוריה ב-Cloud Storage כדי להשתמש בה כסמל של המחבר.
  4. לוחצים על הבא.
  5. בקטע Connector specification (מפרט המחבר), מגדירים את השדות הבאים:
    1. סוג מחבר בהתאמה אישית: בוחרים את סוג המחבר בהתאמה אישית.
    2. מפרט המחבר: מזינים את כתובת ה-URL הציבורית של מפרט Open API או מעלים את קובץ המפרט לקטגוריה של Cloud Storage.
  6. בודקים את פרטי ההגדרה של מחבר הנתונים ולוחצים על יצירה.

אם יצירת המחבר הצליחה, המחבר החדש יופיע ב דף המחברים המותאמים אישית, ואם זה מחבר חדש, תיווצר גם גרסה ראשונה של המחבר. אפשר לראות את פרטי הגרסה בכרטיסייה Version (גרסה) בדף Custom Connector details (פרטים של מחבר בהתאמה אישית). מידע נוסף זמין במאמר .

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

API

בדוגמאות הבאות של פקודות אפשר לראות איך ליצור מחבר בהתאמה אישית באמצעות ממשקי ה-API של Integration Connectors:

  1. יוצרים את המחבר. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CUSTOM_CONNECTOR_NAME: שם של מחבר בהתאמה אישית.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • UNIQUE_IDENTIFIER: מזהה ייחודי של המחבר. לדוגמה custom-connector-1.
  2. מגדירים את הגרסה של המחבר המותאם אישית. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL",}' \
"https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"

    3. מחליפים את מה שכתוב בשדות הבאים:

    • ‫SPECIFICATION_URL: כתובת ה-URL של מפרט Open API. לדוגמה, https://petstore3.swagger.io/api/v3/openapi.json.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫VERSION_NUMBER: מספר הגרסה של המחבר. לדוגמה, 2.

יצירה עם קישוריות עקיפה

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

המסוף

  1. במסוף, עוברים לדף Integration Connectors > Custom connectors, ואז בוחרים או יוצרים פרויקט ב- Google Cloud .

    מעבר לדף Custom connectors

  2. לוחצים על יצירת חדש כדי לפתוח את הדף יצירת מחבר בהתאמה אישית.
  3. בקטע פרטי המחבר, מגדירים את השדות הבאים:
    1. שם המחבר: מזינים שם למחבר.
    2. השם המוצג: מזינים שם מוצג למחבר.
    3. תיאור: מזינים תיאור.
    4. הגדרת יעד המחבר לגישה לשרת העורפי: מפעילים את האפשרות הזו. כך מוצגים בדף קטעי ההגדרות הנוספים.
    5. חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
    6. לוגו: מעלים את התמונה לקטגוריה ב-Cloud Storage כדי להשתמש בה כסמל של המחבר.
  4. לוחצים על הבא.
  5. בקטע Connector specification (מפרט המחבר), מגדירים את השדות הבאים:
    1. סוג מחבר בהתאמה אישית: בוחרים את סוג המחבר בהתאמה אישית.
    2. מפרט המחבר: מזינים את כתובת ה-URL הציבורית של מפרט Open API או מעלים את קובץ המפרט לקטגוריה של Cloud Storage.
  6. לוחצים על הבא.
  7. בקטע Connector destination (יעד המחבר), מגדירים את השדות הבאים:
    1. סוג היעד: בוחרים באפשרות כתובת המארח.
    2. מארח: מזינים את שם המארח שבו פועל שירות הביניים, וכוללים את הסכימה http:// או https://.
    3. יציאה: מזינים את מספר היציאה של שירות הביניים.
  8. לוחצים על הבא.
  9. בקטע Connector authentication בוחרים את סוג האימות של שירות הביניים ומזינים את הפרטים המתאימים בהתאם להנחיות. בשלב הזה מגדירים את האימות מ-Integration Connectors לשירות ביניים.

    אי אפשר להגדיר את הגדרות האימות משירות הביניים לקצה העורפי ב-Integration Connectors. שירות הביניים קובע איך הוא רוצה לבצע אימות מול הקצה העורפי.

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

    • אימות באמצעות חשבון שירות
    • אימות באמצעות מפתח API
    • ‫OAuth 2.0 – אימות פרטי כניסה של לקוח
    • אימות בסיסי
    • אימות סיכום

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

    אם הגישה למשאבי ה-API לא מוגבלת ולא נדרש אימות, בוחרים באפשרות No Authentication (ללא אימות).

  10. לוחצים על הבא.
  11. בקטע Backend variables, מזינים את הערכים שרוצים לשלוח לשרת העורפי דרך שירות הביניים. צריך להגדיר את הערכים כצמדי מפתח/ערך. כדי להזין צמד מפתח/ערך, לוחצים על הוספת משתנה, ואז מגדירים את השדות הבאים:
    • Key (מפתח): מזינים את שם המפתח.
    • סוג הערך: בוחרים את סוג הנתונים של המשתנה.
    • השם המוצג: מזינים שם מוצג.
    • מיקום: מציינים איך רוצים שהמחבר ישלח את המשתנים לשירות המתווך. האפשרויות הזמינות הן: Header,‏ Request payload ו-Query parameter.
    • אפשר גם לבחור באפשרות Required כדי לציין שהמשתנה הוא משתנה חובה.
  12. לוחצים על הבא.
  13. בודקים את פרטי ההגדרה של מחבר הנתונים ולוחצים על יצירה.

אם יצירת המחבר תצליח, המחבר החדש שנוצר יוצג בדף המחברים המותאמים אישית, ואם זה מחבר חדש, תיווצר גם גרסה ראשונה של המחבר. אפשר לראות את פרטי הגרסה בכרטיסייה Version (גרסה) בדף Custom Connector details (פרטים של מחבר בהתאמה אישית). מידע על יצירה ועריכה של גרסה של מחבר בהתאמה אישית זמין במאמר ניהול גרסאות של מחברים בהתאמה אישית.

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

הגדרת אימות

מזינים את הפרטים בהתאם לאימות שבו רוצים להשתמש.

  • אימות של חשבון שירות

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

    • היקפים: בוחרים את היקפי OAuth 2.0 הנדרשים מהתפריט הנפתח. מידע נוסף זמין במאמר בנושא היקפי גישה.
  • אימות באמצעות מפתח API

    בוחרים באפשרות הזו כדי לבצע אימות באמצעות מפתח API.

    • מפתח API: בוחרים את הסוד של מפתח ה-API ב-Secret Manager.
    • גרסת Secret: בוחרים את גרסת ה-Secret.
    • שם הפרמטר של מפתח ה-API: מזינים שם פרמטר למפתח ה-API. מפתח API נשלח לשרת הקצה העורפי שלכם כצמד מפתח/ערך. הערך שמזינים כאן ישמש כשם המפתח של מפתח ה-API שנבחר קודם.
    • מיקום מפתח ה-API: בוחרים את המיקום שבו רוצים להוסיף את מפתח ה-API בבקשה.
  • OAuth 2.0 – הענקת פרטי כניסה של לקוח
    • ‫Client ID: מזהה הלקוח שמשמש לאימות בשירות ביניים.
    • סוד לקוח: סוד ב-Secret Manager שמכיל את סוד הלקוח לאימות בשירות ביניים.
    • פורמט הבקשה לאסימון גישה: פורמט הבקשה שמשמש לבקשות שנשלחות כדי לאחזר אסימון גישה משרת האימות. בוחרים באפשרות body כדי להעביר את מזהה הלקוח ואת הסוד כגוף הבקשה, או באפשרות header כדי להעביר אותם ככותרת מקודדת.
    • נתיב לבקשת טוקן: נתיב הבקשה שיוצמד לכתובת ה-URL של שרת האימות כדי לאחזר את כתובת ה-URL של טוקן הגישה.
  • Basic Authentication
    • שם משתמש: שם המשתמש שמשמש לאימות לשירות ביניים.
    • סיסמה: סוד ב-Secret Manager שמכיל את הסיסמה שמשויכת לשם המשתמש שצוין.
  • Digest Authentication
    • שם משתמש: שם המשתמש שמשמש לאימות לשירות ביניים.
    • סיסמה: סוד ב-Secret Manager שמכיל את הסיסמה שמשויכת לשם המשתמש שצוין.

API

בדוגמאות הבאות של פקודות אפשר לראות איך ליצור מחבר בהתאמה אישית באמצעות ממשקי ה-API של Integration Connectors:

  1. יוצרים את המחבר. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CUSTOM_CONNECTOR_NAME: שם של מחבר בהתאמה אישית.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • UNIQUE_IDENTIFIER: מזהה ייחודי של המחבר. לדוגמה custom-connector-1.
  2. מגדירים את הגרסה של המחבר המותאם אישית ואת האימות. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL", \
"service_account":"test-sa", \
"enable_backend_destination_config": true, \
"auth_config": { \
"auth_type":"USER_PASSWORD", \
"auth_key": "basic", \
"user_password": { \
"username":"USERNAME", \
"password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
}}, \
"backend_variable_templates": [{ \
"key":"authkey", \
"value_type":"SECRET", \
"display_name":"Authorization Key", \
"required":true, \
"location_type": "HEADER" \
}], \
"destination_configs":[{ \
"key":"base_url", \
"destinations": [{ \
"host":"DESTINATION_HOST_ADDRESS" \
}]} \
]}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"

    3. מחליפים את מה שכתוב בשדות הבאים:

    • ‫SPECIFICATION_URL: כתובת ה-URL של מפרט Open API. לדוגמה, https://petstore3.swagger.io/api/v3/openapi.json.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • USERNAME: שם המשתמש לאימות בשירות ביניים.
    • ‫SECRET_VERSION_NUMBER: מספר הגרסה של הסוד ב-Secret Manager. לדוגמה, 2.
    • ‫DESTINATION_HOST_ADDRESS: כתובת המארח של שירות הביניים. לדוגמה, http://www.test.com:80.
    • ‫CONNECTOR_VERSION_NUMBER: מספר הגרסה של המחבר המותאם אישית. לדוגמה, 1.

יצירת חיבור של מחבר בהתאמה אישית

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

  1. במסוף Cloud, עוברים לדף Integration Connectors > Connections ובוחרים או יוצרים פרויקט בענן.

    כניסה לדף Connections

  2. לוחצים על יצירת חדש כדי לפתוח את הדף יצירת חיבור.
  3. בקטע Location, בוחרים מיקום לחיבור מהשדה Region.

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

  4. לוחצים על הבא.
  5. בקטע פרטי החיבור, מגדירים את השדות הבאים:
    1. מחבר: בוחרים את המחבר המותאם אישית מהרשימה הנפתחת של המחברים הזמינים.
    2. גרסת כלי החיבור: בוחרים את גרסת כלי החיבור מהרשימה הנפתחת של הגרסאות הזמינות.
    3. בשדה Connection name (שם החיבור), מזינים שם לחיבור.

      השמות של החיבורים צריכים לעמוד בקריטריונים הבאים:

      • שמות החיבורים יכולים לכלול אותיות, מספרים או מקפים.
      • האותיות צריכות להיות קטנות.
      • שמות החיבורים צריכים להתחיל באות ולהסתיים באות או במספר.
      • שמות החיבורים לא יכולים להכיל יותר מ-63 תווים.
    4. אפשר גם להזין תיאור לחיבור.
    5. אפשר גם לבחור באפשרות הפעלת רישום ביומן בענן כדי להפעיל רישום ביומן בענן.
    6. חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
    7. אופציונלי: מגדירים את ההגדרות של צומת החיבור:

      • מספר מינימלי של צמתים: מזינים את המספר המינימלי של צמתי חיבור.
      • מספר הצמתים המקסימלי: מזינים את מספר צמתי החיבור המקסימלי.

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

    8. אופציונלי: לוחצים על הוספת תווית כדי להוסיף תווית לקישור בצורה של צמד מפתח/ערך.
  6. לוחצים על הבא.
  7. אם המחבר משתמש בשירות ביניים כדי להתחבר לחלק האחורי של המערכת, צריך לבצע את הפעולות הבאות:

    בקטע יעדים, מגדירים את השדות הבאים:

    1. סוג היעד: בוחרים באפשרות כתובת המארח.
    2. מארח: מזינים את שם המארח שבו פועל שירות הביניים, וכוללים את הסכימה http:// או https://.
    3. יציאה: מזינים את מספר היציאה של שירות הביניים.

    שדה היעד מכיל כברירת מחדל את כתובת ה-URL של המפרט מתוך מפרט OpenAPI. אם יש כמה כתובות URL של שרתים, מוצגת הראשונה.

  8. לוחצים על הבא.
  9. בקטע אימות, מזינים את פרטי האימות של ה-backend.
    • אם מתחברים ישירות אל ה-Backend, המערכת של Integration Connectors תבקש להגדיר את האימות של ה-Backend.
    • אם אתם מתחברים לעורף הקצה באופן עקיף דרך שירות ביניים, לא תתבקשו להגדיר פרטי אימות ב-Integration Connectors. במהלך יצירת המחבר, כבר הגדרתם את האימות בין Integration Connectors לבין שירות הביניים. ב-Integration Connectors לא צריך להגדיר את האימות בין שירות הביניים לבין הקצה העורפי. שירות הביניים הוא זה שמחליט איך לבצע אימות מול הקצה העורפי.
  10. לוחצים על הבא.
  11. בודקים את פרטי ההגדרה של החיבור ולוחצים על יצירה.

אם יצירת החיבור מצליחה, הוא מופיע בדף 'כל החיבורים', והחיבור זמין ב-Application Integration. אפשר להשתמש בחיבור בשילוב באמצעות המשימה Connectors.

לתשומת ליבכם

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

  • ‫Integration Connectors תומך רק ב-OpenAPI גרסה 3.0 ובכל גרסאות המשנה שלה.
  • מפרט Open API לא מאומת במהלך יצירת מחבר בהתאמה אישית. כשיוצרים חיבור למחבר בהתאמה אישית, כלי Integration Connectors מאמת את המפרט, ואם יש בו שגיאות, החיבור יהיה במצב Error.
  • ב-Integration Connectors אין הבדלה בין ישויות ופעולות. לכן, גם הישויות וגם הפעולות של ה-Backend יופיעו כ-Actions במחבר המותאם אישית.
  • אין תמיכה במחברים מותאמים אישית בפרויקטים שבהם מופעל VPC Service Controls. Google Cloud
  • נקודת הקצה (endpoint) של מפרט Open API ונקודת הקצה של ה-backend צריכות להיות נגישות לציבור. המשמעות היא שאי אפשר ליצור קישוריות פרטית לסביבת הקצה העורפי.
  • סוג המדיה multipart לא נתמך במפרט Open API.
  • אי אפשר לערוך את פרטי הגרסה של מחבר בהתאמה אישית.