Arahan garis miring

Arahan garis miring tersuai membolehkan pengguna menaip /sesuatu dalam kotak mesej untuk memanggil perkhidmatan anda. Antimatter menghantar arahan tersebut ke URL anda dan memaparkan jawapan anda, sama ada kepada pengguna tersebut sahaja atau kepada seluruh saluran.

Cara arahan garis miring berfungsi

1. Seseorang menaip /weather Paris dan menghantarnya. Teks tersebut tidak diposkan.
2. Antimatter menghantar permintaan HTTP ke URL arahan, bersama maklumat tentang siapa yang menaipnya, di mana, dan teks selepas pemicu.
3. Perkhidmatan anda menjawab dalam masa had permintaan (30 saat secara lalai) dengan satu mesej.
4. Antimatter memaparkan jawapan: hanya kepada pengguna tersebut (sementara) atau dalam saluran untuk semua orang.

Arahan tergolong dalam komuniti, dan perkataan pemicu adalah unik dalam komuniti tersebut. Arahan terbina dalam seperti /join, /msg atau /away tidak boleh digantikan. Aplikasi (pelengkap) juga boleh mendaftarkan arahan; lihat Bahagian pelayan.

Cipta arahan

Arahan garis miring custom adalah diaktifkan secara lalai (Benarkan Arahan Garis Miling Custom dalam Konsol Sistem › Integrasi › Pengurusan Integrasi, ServiceSettings.EnableCommands). Pentadbir komuniti dan pentadbir sistem boleh mencipta arahan ini secara lalai.

1. Buka avatar anda di bahagian kanan atas, kemudian Integrasi › Arahan Garis Miling, kemudian Tambah Arahan Garis Miling.
2. Isi Tajuk dan Penerangan (ditunjukkan pada halaman integrasi).
3. Masukkan Perkataan Pencetus Arahan, tanpa garis miring dan tanpa ruang, sebagai contoh weather.
4. Masukkan URL Permintaan dan pilih Kaedah Permintaan: POST (lalai) atau GET.
5. Secara pilihan, tetapkan Nama Pengguna Respons dan Ikon Respons. Ia hanya digunakan apabila pelayan membenarkan integrasi untuk menimpa nama dan ikon (lihat Nama dan ikon).
6. Tanda Lengkapkan Secara Automatik untuk menyenaraikan arahan tersebut apabila pengguna menaip /, dengan Petunjuk Autocomplete (argumennya, seperti [city]) dan Penerangan Autocomplete.
7. Pilih Simpan, dan salin token yang dipaparkan. Perkhidmatan anda menggunakannya untuk memastikan permintaan datang dari pelayan anda.

Dengan API: POST /api/v4/commands dengan {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Kaedah ialah P untuk POST atau G untuk GET. PUT /api/v4/commands/{command_id}/regen_token mengeluarkan token baharu.

Permintaan yang diterima perkhidmatan anda

Arahan POST menghantar badan yang dikodkan sebagai borang (application/x-www-form-urlencoded); arahan GET menghantar medan yang sama dalam strung kueri. Token juga terdapat dalam pengepala Authorization: Token <token>.

Respons

Jawab 200 dengan JSON (Content-Type: application/json):

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

Respons yang bukan JSON dipaparkan sebagai mesej sementara dengan badan sebagai teksnya. 204 No Content tidak memaparkan apa-apa. Status apa pun di luar 200–299 memaparkan ralat kepada pengguna.

Perkhidmatan contoh

Perkhidmatan arahan minimum dalam Python, dengan hanya pustaka piawai:

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

Jika perkhidmatan berjalan pada alamat rangkaian peribadi, pentadbir sistem mesti membenarkannya dalam Benarkan sambungan dalaman tidak dipercayai kepada (ServiceSettings.AllowedUntrustedInternalConnections).

Jawapan lewat

Untuk kerja yang mengambil masa lebih lama daripada had masa, jawab serta-merta (contohnya dengan mesej sementara "Sedang diproses…"), kemudian hantar jawapan sebenar ke response_url. Ia menerima JSON yang sama seperti respons, dan berfungsi sehingga 5 kali dalam tempoh 30 minit selepas arahan.

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

Jalankan arahan dengan API

Skrip dan bot boleh menjalankan sebarang arahan, terbina dalam atau tersuai, seolah-olah mereka telah menaipnya:

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 senaraikan arahan yang boleh disempurnakan secara automatik oleh pengguna dalam komuniti.

Penyempurnaan automatik

Arahan yang dicipta pada halaman integrasi disempurnakan secara automatik dengan pencetus, petua dan penerangannya. Arahan yang didaftarkan oleh aplikasi boleh menerangkan subarahan dan argumennya secara terperinci dengan AutocompleteData, daripada model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) menambah subarahan, yang juga merupakan AutocompleteData.
• AddTextArgument(helpText, hint, pattern) menambah teks bebas.
• AddStaticListArgument(helpText, required, items) menawarkan senarai tetap AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) meminta aplikasi anda untuk cadangan semasa pengguna menaip. URL ialah laluan aplikasi anda, seperti /plugins/com.example.weather/cities. Ia menerima pengguna, saluran dan komuniti, dan mengembalikan senarai JSON {"Item", "Hint", "HelpText"}.

Variasi Named… (AddNamedTextArgument dan lain-lain) menambah bendera --name value. Kedua-dua antara muka web memaparkan cadangan ini.

Semasa seseorang menaip arahan, Fusion memaparkan arahan dan setiap argumennya sebagai blok, dengan blok yang sedang ditaip diserlahkan bersama teks bantuannya. Argumen ini datang dari AutocompleteData atau, jika tiada, dari petunjuk: dalam petunjuk seperti @[username]... #[channel], perkataan yang bermula dengan @ pergi ke argumen orang dan perkataan yang bermula dengan # pergi ke argumen saluran, tanpa mengira urutannya; ... bermaksud argumen itu berulang, dan argumen terakhir mengambil baki teks.

Saluran dalam argumen

Dalam argumen arahan, @ mencadangkan orang, # mencadangkan saluran dan melengkapkannya sebagai #channel-name, dan ~ melengkapkannya sebagai ~channel-name. Antarmuka web dan aplikasi mudah alih Antimatter menulis pautan saluran dengan #, jadi arahan yang mengambil saluran harus menerima kedua-dua bentuk: /join, /mute dan /invite terbina dalam melakukannya, dan petunjuk mereka menyatakan #[channel].