Kauttaviivakomennot

Mukautettu kauttaviivakomento mahdollistaa /jotain-komennon syöttämisen viestiruutuun, jolloin palvelusi kutsutaan. Antimatter lähettää komennon osoitteesi URL:iin ja näyttää vastauksesi joko vain syöttäjälle tai koko kanavalle.

Näin kauttaviivakomento toimii

1. Joku syöttää /weather Paris ja lähettää sen. Tekstiä ei julkaista.
2. Antimatter lähettää HTTP-pyyntön komennon URL:iin, sisältäen tiedot syöttäjästä, sijainnista ja triggerisanan jälkeisestä tekstistä.
3. Palvelusi vastaa viestillä pyynnön aikakatkaisun (oletus 30 sekuntia) puitteissa.
4. Antimatter näyttää vastauksen: joko vain kyseiselle henkilölle (ephemeral) tai kanavassa kaikille.

Komennot kuuluvat yhteisöön, ja triggerisana on ainutlaatuinen sen sisällä. Sisäisiä komentoja, kuten /join, /msg tai /away, ei voi korvata. Sovellukset (liitännäiset) voivat rekisteröidä komentoja; ks. Palvelinosa.

Luo komento

Mukautetut kauttaviivakomennot ovat oletuksena käytössä (Salli mukautetut kauttaviivakomennot kohdassa Järjestelmäkonsoli › Integraatiot › Integraatioiden hallinta, ServiceSettings.EnableCommands). Yhteisön ylläpitäjät ja järjestelmän ylläpitäjät voivat luoda niitä oletuksena.

1. Avaa tiimin valikko, valitse Tiimin asetukset, klikkaa Integraatiot välilehtien lopussa ja valitse sitten Kauttaviivakomennot ja Lisää kauttaviivakomento.
2. Täytä Otsikko ja Kuvaus (näkyvät integraatioiden sivuilla).
3. Syötä Komentotriggersana ilman kauttaviivaa ja välilyöntejä, esimerkiksi weather.
4. Syötä Pyyntö-URL ja valitse Pyyntömenetelmä: POST (oletus) tai GET.
5. Aseta valinnaisesti Vastauksen käyttäjänimi ja Vastauksen kuvake. Niitä käytetään vain, jos palvelin sallii integraatioiden korvata nimet ja kuvakkeet (ks. Nimi ja kuvake).
6. Valitse Automaattitäydennys, jolloin komento näytetään listassa, kun ihmiset syöttävät /. Lisää Automaattitäydön vihje (argumentit, kuten [city]) ja Automaattitäydön kuvaus.
7. Valitse Tallenna ja kopioi näytetty token. Palvelusi käyttää sitä varmistaakseen, että pyynnöt tulevat palvelimeltasi.

API:n kautta: POST /api/v4/commands parametrina {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Metodi on P POST:lle tai G GET:lle. PUT /api/v4/commands/{command_id}/regen_token luo uuden tunnuksen.

Palvelusi vastaanottama pyyntö

POST-komento lähettää lomakekoodatetun ruumiin (application/x-www-form-urlencoded); GET-komento lähettää samat kentät kyselymerkkijonossa. Tunnus on myös Authorization: Token <token> -otsakkeessa.

Vastaus

Vastaa 200 JSON:lla (Content-Type: application/json):

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

Vastaus, joka ei ole JSON, näytetään tilapäisviestinä, jossa ruumis on tekstinä. 204 No Content ei näytä mitään. Mikä tahansa tila, joka ei ole välillä 200–299, näyttää henkilölle virheen.

Palvelun esimerkki

Minimaalinen komentoservice Pythonilla, käyttäen vain standardikirjastoa:

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

Jos palvelu toimii yksityisen verkkoyhteyden osoitteella, järjestelmän ylläpitäjän on sallittava se kohdassa Salli luottamattomat sisäiset yhteydet osoitteisiin (ServiceSettings.AllowedUntrustedInternalConnections).

Viivästyneet vastaukset

Työhön, joka kestää kauemmin kuin aikakatkaisu, vastaa heti (esimerkiksi tilapäisellä viestillä ”Töissä…”), ja lähetä sitten todellinen vastaus osoitteeseen response_url. Vastaus käyttää samaa JSON-muotoa kuin tavallinen vastaus, ja toimii enintään viisi kertaa 30 minuutin aikana komennon jälkeen.

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

Suorita komento API:lla

Skriptit ja botit voivat suorittaa minkä tahansa komennon, olipa se sisäänrakennettu tai mukautettu, aivan kuin ne olisivat kirjoittaneet sen:

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 luetteloitaa komendot, joita käyttäjät voivat täydentää yhteisössä.

Automaattitäydennys

Integraatioiden sivuilla luodut komendot täydentyvät automaattisesti laukaisunsa, vihjeensä ja kuvauksensa perusteella. Sovellusten rekisteröimät komendot voivat kuvata alikomentonsa ja argumenttinsa tarkemmin AutocompleteData-rakenteella, joka luodaan model.NewAutocompleteData(trigger, hint, helpText)-kutsulla:

• AddCommand(sub) lisää alikomennon, joka on itse AutocompleteData-rakenne.
• AddTextArgument(helpText, hint, pattern) lisää vapaata tekstiä.
• AddStaticListArgument(helpText, required, items) tarjoaa kiinteän luettelon AutocompleteListItem{Item, Hint, HelpText}-olioita.
• AddDynamicListArgument(helpText, url, required) hakee ehdotukset sovelluksestasi, kun käyttäjä kirjoittaa. URL on sovelluksesi reitti, kuten /plugins/com.example.weather/cities. Reitti vastaanottaa käyttäjän, kanavan ja yhteisön, ja palauttaa JSON-luettelon {"Item", "Hint", "HelpText"}-olioita.

Named…-muunnelmat (AddNamedTextArgument ja muut) lisäävät --name value-liput. Molemmissa käyttöliittymissä nämä ehdotukset näkyvät. Arvo, jossa on välilyöntejä, voidaan lainausmerkitä, jolloin se täydentyy yhteen argumenttiin, esimerkiksi --name "my remote": kaksoislainausmerkit toimivat kaikissa komennoissa, ja Antimatterin omat komennot, jotka hyväksyvät liput, hyväksyvät myös yksittäiset tai kaarevat lainausmerkit.

Kun joku kirjoittaa komentoa, Fusion näyttää komennon ja sen argumentit blokkeina. Kirjoitettava argumentti on korostettu ja sen ohjeteksti näkyy. Argumentit tulevat AutocompleteData:sta tai, jos sitä ei ole, vihjeestä: vihjeessä, kuten @[username]... #[channel], sanat, jotka alkavat @-merkillä, liitetään henkilöargumenttiin ja sanat, jotka alkavat #-merkillä, kanavaargumenttiin, riippumatta järjestyksestä. Merkki ... tarkoittaa, että argumentti toistuu, ja viimeinen argumentti ottaa vastaan loput tekstistä.

Kanavat argumenteissa

Komenton argumenteissa @ ehdottaa henkilöitä, # ehdottaa kanavia ja täydentää ne muodossa #channel-name, ja ~ täydentää ne muodossa ~channel-name. Antimatterin verkkokeskus ja mobiilisovitus kirjoittavat kanavalinkit muodossa #, joten komennon, joka ottaa kanavan, tulee hyväksyä molemmat muodot: sisäänrakennetut /join, /mute ja /invite hyväksyvät molemmat, ja niiden vihjeet sanovat #[channel].