Perjeles parancsok

Az egyedi perjeles parancs lehetővé teszi, hogy a felhasználók a /something formában írjanak a bejegyzésmezőbe, hogy meghívják a szolgálatod. Az Antimatter elküldi a parancsot a megadott URL-re, és megjeleníti a választ, akár csak a felhasználó számára, akár a teljes csatorna számára.

Hogyan működik a perjeles parancs

1. Valaki beírja a /weather Paris parancsot, és elküldi. A szöveg nem kerül bejegyzésként a csatornába.
2. Az Antimatter HTTP-kérést küld a parancs URL-ére, amely tartalmazza, ki írta, hol, és mi a szöveg a parancs utáni részeként.
3. A szolgálatod a kérés időtúllépési határideje (alapértelmezés szerint 30 másodperc) alatt válaszol egy üzenettel.
4. Az Antimatter megjeleníti a választ: csak az adott felhasználó számára (ideiglenes) vagy a csatornában mindenki számára.

A parancsok egy közösséghez tartoznak, és a parancs szava egyedi a közösségen belül. A beépített parancsok, mint például a /join, /msg vagy /away nem helyettesíthetők. Az alkalmazások (bővítmények) is regisztrálhatnak parancsokat; lásd: A szerverrész.

Parancs létrehozása

Az egyéni perjeles parancsok alapértelmezés szerint engedélyezve vannak (Engedélyezze az egyéni perjel parancsokat a Rendszerkonzol › Integrációk › Integrációkezelés menüben, ServiceSettings.EnableCommands). A közösségi adminisztrátorok és a rendszeradminisztrátorok alapértelmezés szerint létrehozhatnak ilyen parancsokat.

1. Nyissa meg a profilképét a jobb felső sarokban, majd válassza az Integrációk › Perjeles parancsok, és utána az Perjel parancs hozzáadása lehetőséget.
2. Töltsd ki a Cím és a Leírás mezőket (ezek jelennek meg az integrációk oldalain).
3. Adja meg a Parancs kulcsszót, perjel és szóköz nélkül, például weather.
4. Adja meg a Kérés URL címet, és válassza a Kérés módját: POST (alapértelmezett) vagy GET.
5. Szabadon állíthat be Válasz felhasználónevet és Válasz ikont. Ezeket csak akkor használja a rendszer, ha a szerver engedélyezi, hogy az integrációk felülírják a neveket és ikonokat (lásd: Név és ikon).
6. Jelölje be az Automatikus kitöltés opciót, hogy a parancs megjelenjen a listában, amikor valaki beírja a / jelet. Ehhez adjon meg egy Automatikus kiegészítés tippet (például argumentumok, mint [city]) és egy Automatikus kiegészítés leírást.
7. Válaszd a Mentés lehetőséget, és másold ki a megjelenített tokent. A szolgálatod ezt használja annak ellenőrzésére, hogy a kérések a szerveredtől származnak.

API-n keresztül: POST /api/v4/commands a következő testtel: {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. A módszer értéke P a POST, G a GET esetén. A PUT /api/v4/commands/{command_id}/regen_token új token kiállítására szolgál.

A szervered által fogadott kérés

A POST parancs formátumozott törzsként (application/x-www-form-urlencoded) küldi az adatokat, a GET parancs pedig ugyanazokat a mezőket a lekérdezési karakterláncban. A token az Authorization: Token <token> fejlécben is szerepel.

A válasz

Válaszolj 200 státuszkóddal JSON formátumban (Content-Type: application/json):

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

A nem JSON formátumú válasz egy ideiglenes üzenetként jelenik meg, a törzs szövegével. A 204 No Content státusz nem jelenít meg semmit. A 200–299-en kívüli bármely státuszkód hibát jelez a felhasználónak.

Példa szerver

Egy minimális parancsszerver Pythonban, csak a standard könyvtárral:

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()

Ha a szolgáltatás egy privát hálózati címen fut, a rendszeradminisztrátor engedélyeznie kell azt a Nem megbízható belső kapcsolatok engedélyezése ide beállításban (ServiceSettings.AllowedUntrustedInternalConnections).

Késleltetett válaszok

Ha a munka hosszabb ideig tart, mint a időtúllépési határ, azonnal adjon választ (például egy ideiglenes „Foglalkozom vele…” üzenettel), majd küldje el a valódi választ a response_url címre. Ugyanazt a JSON-t várja, mint a válasz, és a parancs kiadásától számított 30 percen belül legfeljebb 5 alkalommal használható.

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

Parancs futtatása a API-val

A szkriptek és botok bármely parancsot, beépítettet vagy egyébit, úgy futtathatnak, mintha beírták volna:

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"}'

A GET /api/v4/teams/{team_id}/commands/autocomplete felsorolja azokat a parancsokat, amelyeket a felhasználók befejezhetnek egy közösségben.

Befejezés

Az integrációs oldalakon létrehozott parancsok a kiváltó szavukkal, utalásukkal és leírásukkal fejeződnek be. Az alkalmazások által regisztrált parancsok részletesen leírhatják alkomandusaikat és argumentumaikat a AutocompleteData segítségével, a model.NewAutocompleteData(trigger, hint, helpText) függvényt használva:

• A AddCommand(sub) hozzáad egy alkomandust, amely szintén egy AutocompleteData.
• A AddTextArgument(helpText, hint, pattern) szabad szöveget ad hozzá.
• A AddStaticListArgument(helpText, required, items) egy rögzített AutocompleteListItem{Item, Hint, HelpText} listát kínál.
• A AddDynamicListArgument(helpText, url, required) az alkalmazástól kér javaslatokat, amíg a felhasználó gépel. Az URL az alkalmazás egy útvonala, például /plugins/com.example.weather/cities. Megkapja a felhasználót, a csatornát és a közösséget, és egy {"Item", "Hint", "HelpText"} JSON listát ad vissza.

A Named… változatok (AddNamedTextArgument és mások) --name value kapcsolókat adnak hozzá. Mindkét webes felület megjeleníti ezeket a javaslatokat.

Amíg valaki beír egy parancsot, a Fusion a parancsot és annak minden argumentumát blokkként jeleníti meg, a beírandó argumentum kiemelve, a hozzá tartozó súgószöveggel. Az argumentumok AutocompleteData-ből származnak, vagy annak hiányában a hintből: egy olyan hintben, mint @[username]... #[channel], a @-vel kezdődő szavak a people argumentumba, a #-vel kezdődő szavak pedig a channel argumentumba kerülnek, bármilyen sorrendben; a ... azt jelenti, hogy az argumentum ismétlődik, és az utolsó argumentum a szöveg maradékát veszi fel.

Csatornák argumentumként

Egy parancs argumentumaiban a @ személyeket, a # csatornákat javasol, és a #channel-name formában egészíti ki őket, a ~ pedig a ~channel-name formában. Az Antimatter webes felülete és mobilalkalmazása a csatorna-hivatkozásokat a # jelöléssel írja, ezért a csatornát fogadó parancsnak mindkét formát el kell fogadnia: a beépített /join, /mute és /invite parancsok ezt megteszik, és a tippjeik a #[channel] formát írják elő.