#שילוב בקשות HTTP ב-תהליך עבודה

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

#סקירה כללית

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

#תרחישי שימוש אופייניים

#אחזור נתונים

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

#הפעלת תהליכים עסקיים

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

#שילוב מערכות

• קריאות מיקרו-שירותים: קריאה ל-API של שירותים אחרים בארכיטקטורות מיקרו-שירותים.
• דיווח נתונים: דיווח נתונים עסקיים לפלטפורמות אנליטיקה, מערכות ניטור.
• שירותי צד שלישי: שילוב שירותי AI, זיהוי OCR, סינתזת דיבור.

#אוטומציה

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

#תכונות

#תמיכה מלאה ב-HTTP

• תומך בכל שיטות ה-HTTP: GET, POST, PUT, PATCH, DELETE.
• תומך בכותרות בקשה מותאמות אישית (Headers).
• תומך בפורמטים מרובים של נתונים: JSON, נתוני טפסים, XML.
• תומך בסוגי פרמטרים שונים: פרמטרי URL, פרמטרי נתיב, גוף בקשה.

#עיבוד נתונים גמיש

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

#אימות אבטחה

• אימות בסיסי (Basic Auth): אימות HTTP בסיסי.
• אסימון נושא (Bearer Token): אימות באמצעות אסימון.
• מפתח API: אימות מפתח API מותאם אישית.
• כותרות מותאמות אישית: תמיכה בכל שיטת אימות.

#שלבי שימוש

#1. ודאו שהתוסף מופעל

צומת בקשת HTTP הוא תכונה מובנית של תוסף תהליך עבודה. ודאו שתוסף תהליך עבודה מופעל.

#2. הוסיפו צומת בקשת HTTP ל-תהליך עבודה

1. צרו או ערכו תהליך עבודה.
2. הוסיפו צומת בקשת HTTP במיקום הרצוי.

3. הגדירו את פרמטרי הבקשה.

#3. הגדירו את פרמטרי הבקשה

#הגדרות בסיסיות

• כתובת URL של הבקשה: כתובת ה-API היעד, תומכת במשתנים.

  https://api.example.com/users/{{$context.userId}}

• שיטת בקשה: בחרו GET, POST, PUT, DELETE וכו'.

• כותרות בקשה: הגדירו כותרות HTTP.

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$context.apiKey}}"
  }

• פרמטרי בקשה:

  • פרמטרי שאילתה (Query Parameters): פרמטרי שאילתה של URL.
  • פרמטרי גוף הבקשה (Body Parameters): נתוני גוף הבקשה (POST/PUT).

#הגדרות מתקדמות

• זמן קצוב (Timeout): הגדירו זמן קצוב לבקשה (ברירת מחדל 30 שניות).
• ניסיון חוזר במקרה של כשל: הגדירו מספר ניסיונות חוזרים ומרווח ביניהם.
• התעלמות מכשל: המשיכו את תהליך העבודה גם אם הבקשה נכשלה.
• הגדרות פרוקסי: הגדירו פרוקסי HTTP (במידת הצורך).

#4. שימוש בנתוני התגובה

לאחר ביצוע צומת בקשת HTTP, ניתן להשתמש בנתוני התגובה בצמתים הבאים:

• {{$node.data.status}}: קוד סטטוס HTTP.
• {{$node.data.headers}}: כותרות תגובה.
• {{$node.data.data}}: נתוני גוף התגובה.
• {{$node.data.error}}: הודעת שגיאה (אם הבקשה נכשלה).

#תרחישי דוגמה

#דוגמה 1: קבלת מידע על מזג האוויר

// Configuration
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
  city: {{$context.city}}
  key: your-api-key

// Use Response
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}

#דוגמה 2: שליחת הודעת WeCom

// Configuration
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
  Content-Type: application/json
Body:
{
  "touser": "{{$context.userId}}",
  "msgtype": "text",
  "agentid": 1000001,
  "text": {
    "content": "Order {{$context.orderId}} has been shipped"
  }
}

#דוגמה 3: שאילתת סטטוס תשלום

// Configuration
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
  Authorization: Bearer {{$context.apiKey}}
  Content-Type: application/json

// Conditional Logic
If {{$node.data.data.status}} equals "paid"
  - עדכנו את סטטוס ההזמנה ל"שולם"
  - שלחו הודעת הצלחת תשלום
Else If {{$node.data.data.status}} equals "pending"
  - שמרו את סטטוס ההזמנה כ"ממתין לתשלום"
Else
  - תעדו כשל בתשלום
  - הודיעו למנהל לטפל בחריגה

#דוגמה 4: סנכרון נתונים ל-CRM

// Configuration
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
  X-API-Key: {{$context.crmApiKey}}
  Content-Type: application/json
Body:
{
  "name": "{{$context.customerName}}",
  "email": "{{$context.email}}",
  "phone": "{{$context.phone}}",
  "source": "NocoBase",
  "created_at": "{{$context.createdAt}}"
}

#הגדרות אימות

#אימות בסיסי (Basic Authentication)

Headers:
  Authorization: Basic base64(username:password)

#אסימון נושא (Bearer Token)

Headers:
  Authorization: Bearer your-access-token

#מפתח API

// In Header
Headers:
  X-API-Key: your-api-key

// Or in Query
Query Parameters:
  api_key: your-api-key

#OAuth 2.0

יש לקבל תחילה access_token, ולאחר מכן להשתמש בו:

Headers:
  Authorization: Bearer {{$context.accessToken}}

#טיפול בשגיאות וניפוי באגים

#שגיאות נפוצות

1. פסק זמן בחיבור: בדקו את חיבור הרשת, הגדילו את זמן הקצוב.
2. 401 לא מורשה: ודאו שפרטי האימות נכונים.
3. 404 לא נמצא: ודאו שכתובת ה-URL נכונה.
4. 500 שגיאת שרת: בדקו את סטטוס השירות של ספק ה-API.

#טיפים לניפוי באגים

1. השתמשו בצומתי יומן: הוסיפו צומתי יומן לפני ואחרי בקשות HTTP כדי לתעד נתוני בקשה ותגובה.

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

3. כלי בדיקה: בדקו את ה-API תחילה באמצעות כלים כמו Postman, cURL.

4. טיפול בשגיאות: הוסיפו לוגיקה מותנית לטיפול בסטטוסי תגובה שונים.

If {{$node.data.status}} >= 200 and {{$node.data.status}} < 300
  - טפלו בלוגיקת הצלחה
Else
  - טפלו בלוגיקת כשל
  - תעדו שגיאה: {{$node.data.error}}

#אופטימיזציית ביצועים

#1. השתמשו בעיבוד אסינכרוני

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

#2. הגדירו זמני קצוב סבירים

הגדירו זמני קצוב בהתבסס על זמני התגובה בפועל של ה-API כדי למנוע המתנה מוגזמת.

#3. הטמיעו אסטרטגיות שמירה במטמון

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

#4. עיבוד אצווה

אם יש צורך לבצע מספר קריאות לאותו API, שקלו להשתמש בנקודות קצה של אצווה (אם נתמך).

#5. ניסיון חוזר במקרה של שגיאה

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

#שיטות עבודה מומלצות לאבטחה

#1. הגנו על מידע רגיש

• אל תחשפו מידע רגיש בכתובות URL.
• השתמשו ב-HTTPS להעברה מוצפנת.
• אחסנו מפתחות API ונתונים רגישים במשתני סביבה או בניהול תצורה.

#2. אמת נתוני תגובה

// Validate response status
if (![200, 201].includes($node.data.status)) {
  throw new Error('API request failed');
}

// Validate data format
if (!$node.data.data || !$node.data.data.id) {
  throw new Error('Invalid response data');
}

#3. הגבלת קצב בקשות

כבדו את מגבלות הקצב של API של צד שלישי כדי למנוע חסימה.

#4. טיהור יומנים

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

#השוואה ל-Webhook

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

#משאבים קשורים

• תיעוד תוסף תהליך עבודה
• תהליך עבודה: צומת בקשת HTTP
• תהליך עבודה: טריגר Webhook
• אימות מפתחות API
• תוסף תיעוד API