משתנים

משתנה הוא רכיב שילוב שמכיל נתונים ומעביר אותם בין המשימות, הטריגרים והקצוות של השילוב.

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

משתנים

ב-Application Integration, משתנים מוגדרים או מאותחלים במקומות שונים:

  • משתני הגדרה: מוגדרים בזמן העיצוב כדי לאחסן את נתוני ההגדרה של השילוב. לדוגמה, אפשר להשתמש בזה כדי להגדיר כתובת אימייל יעד לקבלת התראות, במקום להגדיר את כתובת האימייל הזו בהגדרות השילוב.
  • משתני מערכת: נוצרים באופן אוטומטי על ידי המערכת כדי לאחסן את נתוני ההגדרה של השילוב. לדוגמה, המשתנה ExecutionId מאחסן את מזהה הביצוע של השילוב.
  • משתני שילוב: מוגדרים באופן מפורש בשילוב כדי לעקוב אחרי נתונים במהלך הביצוע של שילוב שלם. לדוגמה, אתם יכולים להגדיר משתנה כדי לאחסן את התוצאה של משימה ולהשתמש בו במשימה הבאה.
  • משתני משימה: מוגדרים באופן מרומז על ידי ביצוע משימות ספציפיות כדי לאחסן את הפלט של המשימה. לדוגמה, המשימה Call REST Endpoint מגדירה את המשתנה responseBody לאחסון גוף התגובה של נקודת הקצה של REST. משתני משימה נקראים גם משתנים שנוצרו אוטומטית. למשתנים שנוצרים אוטומטית יש כלל מיוחד למתן שמות: צריך להשתמש בגרש הפוך משני צידי שם המשתנה.

משתני שילוב

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

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

  • הם משמשים כקלט לשילוב, והם נקראים גם משתני קלט.
  • הערכים האלה מוחזרים כפלט של השילוב, שנקרא גם משתני פלט.
  • משמש לשמירת מצב זמני במהלך ההפעלה של אינטגרציה.

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

כשמסמנים משתנה כמשתנה פלט, מציינים שערך הסופי של המשתנה צריך להיות מוחזר כחלק מהתגובה של השילוב.

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

סוגי נתונים נתמכים

סוגי הנתונים הבאים נתמכים במשתני שילוב:

  • מחרוזת ומערך מחרוזות
  • מספר שלם ומערך של מספרים שלמים
  • Double ו-Double array
  • ערך בוליאני ומערך בוליאני
  • JSON

משתני משימה

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

השם הייחודי של משתנה משימה פועל לפי מוסכמת שמות מיוחדת: הוא משתמש בגרשיים הפוכים סביב שם המשתנה וכולל את מזהה המשימה. הפורמט הוא `<Task ID>_<Variable Name>`.

לדוגמה, למשימה Call REST Endpoint יש פלט לגוף התגובה. אם למשימה הזו יש מזהה של Task_5, שם המשתנה הייחודי של המשימה בגוף התגובה הוא `Task_5_responseBody`.

בחלונית Variables (משתנים), יכול להיות שמשתני המשימה יופיעו לפי שם פלט נפוץ, למשל responseBody, בלי מזהה המשימה או גרשיים הפוכים. כדי לראות את השם המלא והייחודי של המשתנה שנדרש לצורך הפניה, לוחצים על המשתנה בחלונית ומציגים את הפרטים שלו בחלונית השמאלית.

משתני הגדרה

משתני הגדרה מאפשרים להגדיר את השילוב באופן חיצוני. בעזרת משתני הגדרה, אתם יכולים להגדיר היבטים של השילוב, כמו פרטי מחבר, פרטי אימות או נקודות קצה של כתובות URL שמבוססות על סביבת הפיתוח, כמו QA, העברה לבדיקה או ייצור. לא צריך לעדכן את השילוב באופן ידני לפני שמעלים אותו לסביבה חדשה. כשמפרסמים את השילוב, אפשר להזין ערכים למשתני ההגדרה באמצעות התכונה 'Application Integration'.

כדי לצפות במשתני ההגדרה ולערוך אותם שהוגדרו בשילוב, לוחצים על variable_add משתנה הגדרת שילוב בחלונית משתנים. כדי ללמוד איך ליצור משתני הגדרה ולהשתמש בהם, אפשר לעיין במדריך יצירת CICD לשילוב.

משתני מערכת

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

  • ‫ErrorInfo: אם הביצוע נכשל, אפשר לגשת לפרטי השגיאה באמצעות המשתנה ErrorInfo: 
    {
  "ErrorInfo": {
  "message": String,
  "code": Number
  }
}

    כדי לגשת להודעות השגיאה, צריך ליצור משתנה שילוב בשם ErrorMessage. עם זאת, מומלץ להשתמש במשתנה ErrorInfo.message שנוצר על ידי המערכת כדי לגשת להודעות שגיאה.

  • ‫ExecutionMode: מצב ההפעלה על סמך הטריגר. הערכים התקפים הם SYNC ו-ASYNC.
  • ‫ExecutionId: מזהה הביצוע של השילוב.
  • ‫IntegrationName: שם השילוב.
  • ‫Region: האזור של השילוב.
  • ‫ProjectId: מזהה הפרויקט שמכיל את השילוב.

הצגת משתנים

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

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

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

משתנה מעצב השילובים משתנה מעצב השילובים

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

כדי לראות את משתני ההגדרה שמוגדרים בשילוב, לוחצים על variable_add משתנה הגדרת שילוב בחלונית Variables (משתנים). יוצג החלונית Config variables (משתני הגדרה) עם כל משתני ההגדרה שהוגדרו בשילוב. פשוט לוחצים על השדה ערך כדי לערוך את הערך של משתנה ההגדרה.

בתמונה הבאה מוצגת דוגמה לפריסה של החלונית משתני הגדרה:

משתנה של הגדרות אינטגרציה משתנה של הגדרות אינטגרציה

יצירת משתנה

כדי ליצור משתנה:

  1. בסרגל הניווט של כלי העריכה של השילוב, לוחצים על , הסמל להחלפת החלונית, כדי להציג את החלונית משתנים.
  2. לוחצים על +יצירה.
  3. בחלונית Create Variable (יצירת משתנה):
    1. שם: מזינים את שם המשתנה.
    2. סוג משתנה: בוחרים את סוג המשתנה.
      3. סוג נתונים תיאור
      ללא משתנה מקומי בשילוב.
      משתנה הגדרה לשילוב משתנה config בשילוב.
      קלט לשילוב במהלך ההפעלה, המשתנה יסופק כקלט לטריגר שהופעל.
      פלט מהשילוב הערך הסופי של המשתנה בסיום ההרצה צריך להיות הפלט של המתקשר של השילוב.
      קלט ופלט של שילוב בזמן ההפעלה, המשתנה יסופק כקלט לטריגר המופעל, והערך הסופי שלו יועבר כפלט למי שקורא לשילוב.
    3. סוג הנתונים: בוחרים את סוג הנתונים של המשתנה. כדי לזהות את סוג הנתונים של משתנה, אפשר להשתמש בסמל שמופיע ליד שם המשתנה.
      סוג נתונים דוגמה
      מחרוזת Alex
      מספר שלם 30
      ‫ Double 30.5
      בוליאני true
      ‫ JSON { "employee":{"name":"Alex", "age":30, "city":"Mountain View"} }
      מערך מחרוזות Alex, Kai, Raha
      מערך של מספרים שלמים 30, 25, 22
      מערך כפול 30.5, 25.34, 22.134
      מערך בוליאני true, false, false

      מידע על סוגי הנתונים הנתמכים זמין במאמר סוגי נתונים נתמכים.

    4. ערך ברירת מחדל: מזינים את ערך ברירת המחדל של המשתנה. השדה הזה אופציונלי.
    5. סכימה: בוחרים את סכימת ה-JSON של המשתנה.
      • ‫Infer from a sample JSON payload: יצירת סכימת JSON ממטען ייעודי (payload) של JSON לדוגמה. מטען הייעודי לדוגמה נמחק אחרי שנוצרת הסכימה. רק הסכימה שנוצרה תישמר.
      • הזנה של סכימת JSON: מזינים ידנית סכימת JSON שלמה.
      • הסקת מסקנות מערך ברירת המחדל: יצירת סכימת JSON באמצעות ערך ברירת המחדל שסופק.
      • ללא: ללא סכימת JSON.
    6. הסתרת המשתנה ביומנים (תצוגה מקדימה): בוחרים באפשרות הזו כדי להפעיל הסתרה של המשתנה ביומני הביצוע של השילוב. כדי להפעיל מיסוך למשתנה, צריך להפעיל מיסוך משתנים לשילוב ולאזור. מידע על הפעלת מיסוך בשילוב ובאזור זמין במאמרים עריכת שילוב ועריכת אזורים.

      מידע על אנונימיזציה זמין במאמר אנונימיזציה של נתונים רגישים ביומנים.

  4. לוחצים על יצירה.

איך משתנים פועלים בשילובים

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

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

בטבלה הבאה מסוכמים הסוגים השונים של משתנים וההתנהגות שלהם:

סוג המשתנה תיאור התנהגות דוגמה
משתנה הגדרה שמירת נתוני ההגדרה של השילוב. ההגדרה מתבצעת בזמן העיצוב, ואפשר לערוך אותה כשמפרסמים את השילוב. כתובת אימייל יעד לקבלת התראות.
משתנה מערכת נוצר באופן אוטומטי על ידי המערכת. הם לקריאה בלבד ואי אפשר לערוך אותם. המשתנה ExecutionId.
משתנה שילוב עוקב אחרי הנתונים במהלך ההפעלה של שילוב שלם. ההגדרה מתבצעת באופן מפורש בשילוב, ואפשר לערוך אותה במהלך ההרצה של השילוב. משתנה לאחסון התוצאה של משימה.
משתנה של משימה מאחסן את הפלט של משימה ספציפית. הערך מוגדר באופן מרומז על ידי ביצוע משימה, ואי אפשר לערוך אותו. המשתנה responseBody של המשימה Call REST Endpoint.

הפניות למשתנים

המשימות, הטריגרים והקצוות בשילוב קוראים וכותבים למשתנים באמצעות הפניות למשתנים. הפניה למשתנה היא מהצורה $paramKey$, כאשר paramKey הוא שם המשתנה.

$isNameUnique$ = true AND $numAccounts$ >= 1

לדוגמה:

  • תנאי קצה יכול להיראות כך: 
    $isNameUnique$ = true AND $numAccounts$ >= 1

    בדוגמה הזו, isNameUnique הוא משתנה מסוג הנתונים boolean ו-numAccounts הוא פרמטר מסוג הנתונים integer.

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

    • ‫$userName$: מכיל את השם של המשתמש החדש (לדוגמה, Alex).
    • ‫$orderID$: מכיל מזהה הזמנה ייחודי (למשל, ORD-12345).

    התבנית לתוכן האימייל יכולה להיות: 

    Hello $userName$, thank you for your order! Your order ID is $orderID$.

    כששולחים את ההודעה הזו, המערכת מחליפה את ההפניות למשתנים בערכים התואמים שלהם. ההודעה הסופית תהיה: 

    Hello Alex, thank you for your order! Your order ID is ORD-12345.

אפשר להשתמש בהפניות למשתנים במקומות הבאים:

כשמתייחסים למשתנה שנוצר אוטומטית או למשתנה של משימה, צריך להשתמש בשם המלא והייחודי שלו, שכולל גרשיים הפוכים ואת מזהה המשימה, בתוך התוחמים של סימן הדולר. לדוגמה, כדי להתייחס לפלט responseBody של משימה מסוג Call REST Endpoint עם מזהה Task_5, צריך להשתמש ב-$`Task_5_responseBody`$.

מכסות ומגבלות

מידע על מכסות ומגבלות זמין במאמר מכסות ומגבלות.

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