שליפת מטען ייעודי (payload) של API ושליחת אימייל

איך יוצרים שילוב לדוגמה ב-Application Integration בשלבים הבאים מוסבר איך להגדיר את הטריגר, המשימות, הקצוות, המשתנים ומיפויי הנתונים שנדרשים להרצת שילוב מלא.

סקירה כללית

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

לחצו על תראו לי איך כדי לקרוא הסבר מפורט על המשימה ישירות במסוף Google Cloud :

תראו לי איך

יצירת שילוב חדש

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

  1. במסוף Google Cloud, עוברים לדף Application Integration.

    מעבר אל Application Integration

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

    לצורך השימוש במדריך למתחילים הזה, מזינים את השם my-test-integration ואת התיאור Integration for quickstart.

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

הוספה והגדרה של טריגר API

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

כדי להגדיר את הטריגר של ה-API:

  1. בכלי לעריכת שילובים, לוחצים על טריגרים כדי להציג רשימה של טריגרים זמינים.
  2. לוחצים על API trigger (טריגר API) בכלי לעריכת השילובים.
  3. כדי להגדיר את הטריגר, לוחצים על API trigger (טריגר API). יופיע לוח ההגדרות של הטריגר.
  4. השדות תווית ומזהה הטריגר ימולאו אוטומטית על ידי Application Integration. מזהה הטריגר נוצר על ידי המכונה ואי אפשר לערוך את הערך. אבל אפשר לערוך את הערך של המאפיין Label.

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

הוספה והגדרה של משימות

משימה היא קבוצה של שלבים שאפשר להריץ, שיכולה לקבל משתנים כקלט וליצור משתנים כפלט. בדומה לטריגרים, אפשר להשתמש בכל משימה זמינה בשילוב. במדריך הזה לשימוש מהיר נעזר במשימות Call REST Endpoint,‏ Data Mapping ו-Send Email. פרטי ההגדרה של כל משימה מפורטים בשלבים הבאים.

הגדרת המשימה Call REST Endpoint

כדי להגדיר את המשימה Call REST Endpoint:

  1. לוחצים על משימות כדי להציג רשימה של משימות זמינות.
  2. לוחצים על Call REST Endpoint (התקשרות לנקודת קצה של REST) וגוררים אותו למיקום הרצוי בכלי לעריכת שילובים.
  3. כדי להוסיף קשר קצה מהפעלת API אל קריאה לנקודת קצה של REST, מעבירים את העכבר מעל נקודת בקרה בהפעלת API, ואז לוחצים וגוררים קו אל נקודת בקרה במשימה קריאה לנקודת קצה של REST. הקצה מציין את זרימת הבקרה מהטריגר של ה-API למשימה Call REST Endpoint.

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

  4. כדי להגדיר את המשימה, לוחצים על Call REST Endpoint (התקשרות לנקודת קצה של REST). יופיע חלונית ההגדרות של המשימה. מגדירים את המאפיינים הבאים:
    • תווית: מזינים שם מותאם אישית למשימה. לדוגמה, מזינים Call REST Endpoint Task.
    • אימות: במדריך הזה לא נדרש פרופיל אימות. למידע נוסף על שימוש בפרופילי אימות בתרחישים אחרים, ראו יצירת פרופילי אימות ב-Application Integration.
    • קלט למשימה: מזינים את הפרטים של הקריאה לנקודת הקצה של REST. המידע שמוזן כאן משמש כקלט למשימה Call REST Endpoint. בתרשים הבא מוצגים החלקים Task Input ו-HTTP settings של המשימה Call REST Endpoint:

      קלט של משימה של נקודת קצה של שיחת REST קלט של משימה של נקודת קצה של שיחת REST

      הזן את פריטי המידע הבאים:

      • כתובת בסיסית של נקודת הקצה: מזינים https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/en.wikipedia/desktop/user/Tree/monthly/20201001/20201031. ה-API הציבורי הזה מ-wikimedia.org מחזיר את מספר הצפיות בדף של מאמר בשם Tree בחודש מסוים.
      • שיטת HTTP: בוחרים באפשרות GET מהרשימה הנפתחת.
    • הגדרות HTTP: Application Integration מאכלס את הערכים הבאים:
      1. מעקב אחרי הפניות אוטומטיות: True
      2. המשימה צריכה להיכשל בגלל שגיאת HTTP: True
    • פלט המשימה: Application Integration מאכלס שלושה משתנים כדי להכיל את נתוני התשובה שמתקבלים מהקריאה לנקודת הקצה של REST. בתרשים הבא מוצגים הפלט של המשימה וחלקים אחרים של המשימה Call REST Endpoint:

      פלט של משימה של נקודת קצה (endpoint) של שיחת REST פלט של משימה של נקודת קצה (endpoint) של שיחת REST

      כדאי לבדוק את המידע הבא:

      • ‫responseHeader(Call REST Endpoint): המשתנה הזה מכיל את נתוני כותרת התגובה שמשויכים למשימה Call REST Endpoint. הנתונים של המשתנה הם מסוג String (STR).
      • ‫responseBody(Call REST Endpoint): המשתנה הזה מכיל את נתוני גוף התגובה שמשויכים למשימה Call REST Endpoint. הנתונים של המשתנה הם מסוג String (STR).
      • ‫responseStatus(Call REST Endpoint): המשתנה הזה מכיל את נתוני סטטוס התגובה שמשויכים למשימה Call REST Endpoint. הנתונים של המשתנה הם מסוג String (STR).
    • בשאר השדות צריכים להיות ערכי ברירת המחדל הבאים:
      • אסטרטגיית הביצוע של המשימה הזו: When all tasks succeed
      • מדיניות ההפעלה של המשימה הבאה: Run all match

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

הוספה והגדרה של משימת מיפוי נתונים

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

  1. לוחצים על משימות כדי להציג רשימה של משימות זמינות.
  2. לוחצים על מיפוי נתונים וממקמים אותו בכלי לעריכת שילובים.
  3. כדי להוסיף חיבור קצה מ-Call REST Endpoint אל Data Mapping, מעבירים את העכבר מעל נקודת בקרה ב-Call REST Endpoint, ואז לוחצים וגוררים קו אל נקודת בקרה במשימה Data Mapping. הקצה מציין את זרימת הבקרה מהמשימה Call REST Endpoint למשימה Data Mapping.
  4. כדי להגדיר את המשימה, לוחצים על המשימה מיפוי נתונים. יופיע חלונית ההגדרות של המשימה.
  5. לוחצים על פתיחת הכלי למיפוי נתונים.

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

    במדריך למתחילים הזה, יוצרים מיפוי באמצעות responseBody(Call REST Endpoint) כקלט:

    1. גוררים את המשתנה responseBody מהחלונית משתנים לשורה הראשונה של קלט.
    2. לוחצים על + (הוספת פונקציה) בצ'יפ משתנים responseBody כדי לראות את רשימת הפונקציות הזמינות. אפשר להחיל מספר פונקציות כדי לשנות את הנתונים במשתנה הקלט.

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

      • לוחצים על TO_JSON() כדי להמיר את המחרוזת responseBody ל-JSON.
      • לוחצים על + (הוספת פונקציה) בצ'יפ משתנים responseBody כדי לבחור את הפונקציה GET_PROPERTY() ולשרשר אותה.
      • כדי להוסיף את פרמטר הקלט של GET_PROPERTY(), לוחצים על משתנה או ערך ובקטע ערך מזינים items.

        הפונקציה הזו תחלץ מאפיין ממטען ייעודי (payload) של JSON. מעבירים את הנכס items כפרמטר לפונקציה הזו. הפעולה הזו תחזיר רשימה של שמות המוצרים בלבד, ללא פרטי מוצר אחרים. הפונקציה צריכה להיראות כך: 

        responseBody(Call REST Endpoint).TO_JSON().GET_PROPERTY(items)
      • אם רוצים להסיר או למחוק פונקציה, לוחצים על הסמל -.
    3. לוחצים על השדה הראשון בעמודה Output (פלט) כדי ליצור משתנה פלט חדש שיכיל את הערך של הנתונים שעברו טרנספורמציה. ממלאים את השדות הבאים:
      • בשדה שם מזינים JSONList.
      • ברשימה סוג משתנה בוחרים באפשרות פלט משילוב.
      • מהרשימה סוג נתונים בוחרים באפשרות JSON.
      • כדי ליצור את המשתנה ולסגור את החלונית, לוחצים על Create (יצירה). המשתנה החדש JSONList יופיע ברשימה Variables (משתנים) בצד ימין של הכלי לעריכת מיפוי נתונים.
    4. אחרי שמסיימים את המיפוי, סוגרים את הכלי לעריכת מיפוי נתונים. כל השינויים יישמרו אוטומטית. בתמונה הבאה מוצג כלי מיפוי הנתונים עם המיפוי שנוצר במדריך למתחילים הזה:

      עורך מיפוי נתונים עורך מיפוי נתונים

הוספה והגדרה של המשימה 'שליחת אימייל'

כדי להגדיר את המשימה שליחת אימייל:

  1. בוחרים באפשרות משימות בכלי לעריכת שילובים כדי להציג את רשימת המשימות הזמינות.
  2. לוחצים על Send Email (שליחת אימייל) וממקמים אותו בעורך השילוב.
  3. מוסיפים חיבור קצה ממיפוי נתונים אל שליחת אימייל. כדי לעשות זאת, מעבירים את העכבר מעל נקודת בקרה במיפוי נתונים, ואז לוחצים וגוררים קו אל נקודת בקרה במשימה שליחת אימייל. הקצה מציין את זרימת הבקרה מהמשימה מיפוי נתונים למשימה שליחת אימייל.
  4. כדי להגדיר את המשימה, לוחצים על שליחת אימייל. יופיע חלונית ההגדרות של המשימה. בקטע Task Input, מגדירים את המאפיינים הבאים:
    • אל הנמען/ים: מזינים את כתובת האימייל. תשתמשו באימייל הזה כדי לאשר שההטמעה הושלמה בהצלחה.
    • נושא: מזינים Email from Application Integration.
    • גוף ההודעה בטקסט פשוט: בוחרים את המשתנה JSONList שנוצר קודם במשימה מיפוי נתונים.
    • אפשר להשאיר את שאר האפשרויות בהגדרת ברירת המחדל.

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

אימות החיבורים הנדרשים ל-Edge

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

החיבור המלא אמור להופיע כמו באיור הבא:

תמונה שבה מוצגת הזרימה של מדריך למתחילים תמונה שבה מוצגת הזרימה של מדריך למתחילים

בדיקת השילוב

כדי לבדוק את השילוב החדש:

  1. לוחצים על בדיקה בסרגל הכלים של עורך השילוב.

    מופיעה החלונית Test Integration (בדיקת השילוב).

  2. לוחצים על Test integration (בדיקת השילוב).

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

בסיום מוצלח של ההגדרה, האינטגרציה שולחת אימייל עם ערכי ה-JSON לכתובת האימייל שצוינה במשימה Send Email. מאשרים את קבלת האימייל בתוכנת האימייל.

האימייל שנשלח על ידי השילוב צריך להכיל גוף שדומה לזה: 

[{
   "project": "en.wikipedia",
   "article": "Tree",
   "granularity": "monthly",
   "timestamp": "2020100100",
   "access": "desktop",
   "agent": "user",
   "views": 33828.0
}]

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

  1. לוחצים על Logs (יומנים) בסרגל הכלים של כלי העריכה של השילוב.
  2. בדף יומני הרצה אפשר לראות פרטים על כל ניסיון להפעיל שילוב. כל רשומה כוללת פרטים על ניסיון ההפעלה, כולל:
    • שם השילוב
    • מזהה ביצוע
    • סטטוס
    • שעת ההתחלה
    • משך הזמן
    • גרסת השילוב
    • מזהה הטריגר
    • Cloud Logging
  3. לוחצים על החץ להרחבה (>) לצד השילוב שהופעל כדי לראות רשימה מורחבת של משימות ומשתנים בשילוב, יחד עם סטטוס המשימה ומטעני משתנים.

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

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