פקודות לוכסן

פקודת לוכסן מותאמת מאפשרת למשתמשים להקליד /something בתיבת ההודעה כדי לקרוא לשירות שלך. Antimatter שולח את הפקודה לכתובת URL שלך ומציג את תשובתך, או רק לאותו אדם או לכל הערוץ.

איך פקודת לוכסן עובדת

1. מישהו מקליד /weather Paris ושולח. הטקסט אינו מפורסם.
2. Antimatter שולח בקשת HTTP לכתובת URL של הפקודה, עם פרטי מי הקליד, איפה, והטקסט אחרי מילת ההפעלה.
3. השירות שלך עונה תוך פרק הזמן המוגדר לבקשה (30 שניות כברירת מחדל) עם הודעה.
4. Antimatter מציג את התשובה: רק לאותו אדם (זמנית) או בערוץ לכל האנשים.

פקודות שייכות לקהילה, ומילת הפעלה ייחודית בתוכה. פקודות מובנות כמו /join, /msg או /away אינן ניתנות להחלפה. אפליקציות (תוספים) יכולות גם הן להרשיל פקודות; ראו החלק של השרת.

יצירת פקודה

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

1. פתחו את האווטאר שלכם בפינה הימנית העליונה, ואז אינטגרציות › פקודות לוכסן, ואז הוספת פקודת לוכסן.
2. מלאו את הכותרת ואת התיאור (מוצג בדפי האינטגרציות).
3. יש להזין את מילת הפעלה לפקודה, ללא סימן לוכסן וללא רווחים, לדוגמה weather.
4. יש להזין את כתובת URL לבקשה ולבחור את שיטת בקשה: POST (ברירת המחדל) או GET.
5. ניתן להגדיר באופן אופציונלי שם משתמש לתגובה וסמל תשובה. הם משמשים רק כאשר השרת מאפשר לאינטגרציות להחליף שמות וסמלים (ראו שם וסמל).
6. סמנו השלמה אוטומטית כדי להציג את הפקודה כשמשתמשים מקלידים /, עם רמז להשלמה אוטומטית (הארגומנטים שלה, כמו [city]) ו-תיאור להשלמה אוטומטית.
7. בחרו שמירה, והעתיקו את האסימון המוצג. השירות שלך משתמש בו כדי לוודא שהבקשות מגיעות מהשרת שלכם.

באמצעות API: POST /api/v4/commands עם {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. השיטה היא P עבור POST או G עבור GET. PUT /api/v4/commands/{command_id}/regen_token מנפיק טוקן חדש.

הבקשה שהשירות שלך מקבל

פקודת POST שולחת גוף בקשה בקידוד טופס (application/x-www-form-urlencoded); פקודת GET שולחת את אותם שדות במחרוזת השאילתה. הטוקן נמצא גם בכותרת Authorization: Token <token>.

התשובה

מענה 200 עם JSON (Content-Type: application/json):

{
  "response_type": "in_channel",
  "text": "Paris: 18 °C, light rain",
  "attachments": []
}

תשובה שאינה JSON מוצגת כהודעה זמנית עם הגוף כטקסט. 204 No Content אינו מציג כלום. כל סטטוס מחוץ לטווח 200–299 מציג למשתמש שגיאה.

דוגמת שירות

שירות פקודה מינימלי ב-Python, עם ספריית הסטנדרט בלבד:

import hmac
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs

TOKEN = "the token shown when you saved the command"

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["Content-Length"])).decode()
        form = {key: values[0] for key, values in parse_qs(body).items()}
        if not hmac.compare_digest(form.get("token", ""), TOKEN):
            self.send_response(401)
            self.end_headers()
            return
        answer = {
            "response_type": "ephemeral",
            "text": f"Hello @{form['user_name']}, you asked for: {form.get('text', '')}",
        }
        data = json.dumps(answer).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(data)

HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()

אם השירות פועל על כתובת רשת פרטית, מנהל מערכת חייב לאשר אותו באפשרות חיבורים פנימיים לא אמורים אל (ServiceSettings.AllowedUntrustedInternalConnections).

תשובות מושהיות

עבור עבודה שאורכה עולה על תום הזמן, יש לענות מיד (למשל עם הודעה זמנית "עובדים על זה…"), ולאחר מכן לשלוח את התשובה האמיתית ב-POST לresponse_url. היא מקבלת את אותו JSON כמו התשובה, ועובדת עד 5 פעמים תוך 30 דקות מהפקודה.

curl -X POST "$RESPONSE_URL" -H 'Content-Type: application/json' \
  -d '{"response_type": "in_channel", "text": "Report ready: https://reports.example.com/42"}'

הרצת פקודה באמצעות ה-API

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

curl -X POST https://chat.example.com/api/v4/commands/execute \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$CHANNEL_ID'", "command": "/weather Paris"}'

GET /api/v4/teams/{team_id}/commands/autocomplete מציגה את הפקודות שאנשים יכולים להשלים אוטומטית בקהילה.

השלמה אוטומטית

פקודות שנוצרו בדפי האינטגרציות מושלמות אוטומטית עם הטרigger, ההרמז והתיאור שלהן. פקודות שרשומות על ידי אפליקציות יכולות לתאר את תת-הפקודות והארגומנטים שלהן בפרטי פרטים באמצעות AutocompleteData, מתוך model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) מוסיף תת-פקודה, שהיא עצמה AutocompleteData.
• AddTextArgument(helpText, hint, pattern) מוסיף טקסט חופשי.
• AddStaticListArgument(helpText, required, items) מציע רשימה קבועה של AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) מבקש מהאפליקציה שלך הצעות בזמן שהמשתמשים מקלידים. ה-URL הוא נתיב של האפליקציה שלך, למשל /plugins/com.example.weather/cities. הוא מקבל את המשתמש, הערוץ והקהילה, ומחזיר רשימת JSON של {"Item", "Hint", "HelpText"}.

הגרסאות Named… (AddNamedTextArgument ואחרות) מוסיפות דגלי --name value. שני ממשקי האתר מציגים הצעות אלה.

כשמישהו מקליד פקודה, Fusion מציגה את הפקודה ואת כל אחד מהארגומנטים שלה כבלוק, כאשר הבלוק שנקלט כרגע מודגש יחד עם טקסט העזרה שלו. הארגומנטים מגיעים מAutocompleteData או, אם אין, מהרמז: ברמז כמו @[username]... #[channel], מילים המתחילות ב@ הולכות לארגומנט האנשים ומילים המתחילות ב# לארגומנט הערוצים, ללא תלות בסדר; ... פירושו שהארגומנט חוזר, והארגומנט האחרון לוקח את שאר הטקסט.

ערוצים בארגומנטים

בארגומנטים של פקודה, @ מציע אנשים, # מציע ערוצים ומשלים אותם כ#channel-name, ו~ משלים אותם כ~channel-name. ממשק ה-Web והאפליקציה המובייל של Antimatter כותבים קישורי ערוצים עם #, ולכן פקודה המקבלת ערוץ צריכה לקבל את שני הצורות: הפקודות המובנות /join, /mute ו/invite עושות זאת, והרמזים שלהן אומרים #[channel].