Zum Hauptinhalt springen

ToDiscord@1

Der Node ToDiscord@1 postet eine Nachricht in einen Discord-Kanal über die Bot-API (POST /channels/{id}/messages). Er unterstützt einfachen Inhalt, ein einzelnes Embed und einen Dateianhang, der aus einer System.Reporting/FileSystemItem-Entität stammt. Um in einen Thread zu posten, übergeben Sie die Snowflake des Threads als channelId — Threads sind im Datenmodell von Discord Kanäle. Die Anmeldedaten stammen aus einer zentral verwalteten DiscordConfiguration-Entität; der Node schlägt sie namentlich über die pipeline-bezogene globale Konfiguration nach.

Adapter-Voraussetzungen​

  • Allgemeine Verfügbarkeit: Mesh Adapter.
  • Eine DiscordConfiguration-Entität muss existieren und der Pipeline zugeordnet sein (über die Standard-Uses-Assoziation).
  • Um Anhänge zu senden, muss der Tenant das CK-Paket System.Reporting (den Eigentümer von FileSystemItem) geladen haben. Dieselbe Einschränkung wie bei CreateFileSystemUpdate@1 und GenerateAndStoreReport@1.

Node-Konfiguration​

Zu den Feldern targetPath, targetValueWriteMode und targetValueKind siehe Überblick. Das Feld path wird in diesem Node nicht verwendet.

Konfigurationsoptionen​

Die meisten benutzerorientierten Felder akzeptieren entweder einen literalen Wert oder einen JSONPath ({Field} oder {Field}Path). Wenn beide gesetzt sind, gewinnt der Pfad; wenn der Pfad zu leer aufgelöst wird, wird der Literalwert verwendet.

  • serverConfiguration (erforderlich): Name des globalen Konfigurationseintrags, der die DiscordConfiguration enthält (Bot-Token + optionale Guild-ID).

  • channelId / channelIdPath (eines erforderlich): Discord-Kanal-Snowflake-ID. Um einen Thread anzusprechen, übergeben Sie hier die Snowflake des Threads — Discord behandelt Threads als Kanäle.

  • content / contentPath (optional): Nachrichteninhalt.

  • embedTitle / embedTitlePath, embedDescription / embedDescriptionPath, embedColor / embedColorPath (optional): ein einzelnes Embed. embedColor als Literal ist eine Ganzzahl (0xRRGGBB); die Pfadform akzeptiert auch #RRGGBB und einen Dezimal-String.

  • attachmentFileSystemItemRtId / attachmentFileSystemItemRtIdPath (optional): RtId eines System.Reporting/FileSystemItem, dessen gebundene Binärdaten der Nachricht angehängt werden. Der Node löst die Nutzdaten über das Content.BinaryId der Entität auf und wählt den an Discord gesendeten Dateinamen anhand der unten stehenden Rangfolge.

  • attachmentFilename / attachmentFilenamePath (optional): expliziter Dateiname-Override. Wenn gesetzt, hat er Vorrang vor den eigenen Feldern des FileSystemItem. Nützlich, wenn der Aufrufer über Domänen-Metadaten einen besseren Namen hat (z. B. eine Rechnungsnummer), der sich nicht im FileSystemItem selbst widerspiegelt.

    Dateiname-Rangfolge (höchste → niedrigste): attachmentFilename → FileSystemItem.Name → FileSystemItem.Content.Filename. Die ersten beiden erfassen die Benutzerabsicht (das Label des Eintrags in einem Ordner); Content.Filename sind Blob-Metadaten, die beim Ingest erfasst wurden und als Implementierungsdetail abweichen, wenn die Entität später umbenannt wird — daher ist es ein Fallback letzter Instanz.

  • mentionPolicy (optional, Standard None): steuert, welche Erwähnungssyntax im Nachrichteninhalt tatsächlich Benachrichtigungen auslöst. Discord-Erwähnungssyntax: <@USER_SNOWFLAKE> für einen Benutzer, <@&ROLE_SNOWFLAKE> für eine Rolle und die literalen Zeichenketten @everyone / @here für die breiten Pings. Die Richtlinie ist eine Typ-Whitelist über die bereits im Inhalt vorhandene Syntax — sie schlägt niemanden namentlich nach. Werte:

    • None — nichts löst eine Benachrichtigung aus. Erwähnungen im Inhalt werden weiterhin als „@username" dargestellt, aber kein Empfänger wird gepingt. Sicherer Standard für Pipelines, die vorgelagerte Daten wiedergeben, bei denen @everyone oder verirrte <@id> versehentlich oder durch Injection auftreten können.
    • Users — nur die <@id>-Syntax im Inhalt löst aus; <@&id> und @everyone/@here werden dargestellt, pingen aber nicht.
    • Roles — nur die <@&id>-Syntax löst aus.
    • UsersAndRoles — Benutzer- und Rollen-Erwähnungen lösen aus; @everyone/@here werden unterdrückt.
    • All — alles Erwähnte löst aus; entspricht dem Discord-Standard, wenn allowed_mentions weggelassen wird.
    • Custom — verwenden Sie allowedMentionsPath, um ein rohes Discord-allowed_mentions-Objekt bereitzustellen. Nötig, wenn Sie nur bestimmte Benutzer-/Rollen-Snowflakes pingen möchten (z. B. {"parse":[],"users":["111"]}) statt jeder Erwähnung dieses Typs im Inhalt.

  • allowedMentionsPath (optional): JSONPath, der zu einem rohen Discord-allowed_mentions-Objekt aufgelöst wird. Wird nur konsultiert, wenn mentionPolicy Custom ist. Der Node bricht sofort ab, wenn der Pfad nicht gesetzt ist oder zu null aufgelöst wird. Die vollständige Objektform finden Sie in Discords Allowed-Mentions-Referenz.

  • timeoutSeconds (optional, Standard 30): Timeout des HTTP-Requests.

  • targetPath (optional, Standard leer): wenn gesetzt, wird die JSON-Antwort der Discord-API in diesen Pfad geschrieben. Nützlich, um die Nachrichten-id für spätere Änderungen zu erfassen; die Antwort trägt außerdem channel_id, timestamp und das vollständige Nachrichtenobjekt.

Mindestens eines von content, embed* oder attachment* muss zu einem Wert aufgelöst werden — Discord lehnt leere Nachrichten ab.

Anwendungsbeispiele​

Eine einfache Nachricht posten​

transformations:
- type: ToDiscord@1
  description: Notify deploy channel
  serverConfiguration: discord-main
  channelId: '123456789012345678'
  content: 'Deployment finished.'

Ein Embed posten und die Nachrichten-ID erfassen​

transformations:
- type: ToDiscord@1
  description: Post status + capture id for later update
  serverConfiguration: discord-main
  channelId: '123456789012345678'
  embedTitle: 'Run started'
  embedDescriptionPath: '$.status.description'
  embedColor: 0x64CEB9
  targetPath: '$.discordMsg'

Den Bereitschaftsbenutzer aus vorgelagerten Daten pingen​

Die Pipeline hat die Snowflake eines Bereitschaftsbenutzers aufgelöst und interpoliert sie mithilfe der <@id>-Syntax von Discord in den Inhalt. Die Users-Richtlinie lässt die <@id> eine Benachrichtigung auslösen, während sie ein versehentliches @everyone weiterhin unterdrückt.

transformations:
- type: ToDiscord@1
  description: Page the on-call
  serverConfiguration: discord-main
  channelId: '123456789012345678'
  contentPath: '$.alert.message'  # e.g. "Pager: <@111222333444555666> DB saturated"
  mentionPolicy: Users

Kritischer Alarm, der @everyone pingt​

Überschreiben Sie den sicheren Standard, um den gesamten Kanal zu benachrichtigen. @everyone ist in Discord eine literale Zeichenkette (keine spitzen Klammern, keine Snowflake).

transformations:
- type: ToDiscord@1
  description: Wake everyone up
  serverConfiguration: discord-main
  channelId: '123456789012345678'
  content: '@everyone production is down'
  mentionPolicy: All

In einen Thread mit einem Dateianhang posten​

Übergeben Sie die Snowflake des Threads als channelId — Discord behandelt Threads als Kanäle. GenerateAndStoreReport@1 schreibt eine FileSystemItem-RtId in den Datenkontext, was genau das ist, was attachmentFileSystemItemRtIdPath erwartet.

transformations:
- type: GenerateAndStoreReport@1
  # ... produces $.reportRef.fileSystemRtId
- type: ToDiscord@1
  description: Attach generated report to a thread
  serverConfiguration: discord-main
  channelId: '987654321098765432'  # thread snowflake
  content: 'Report ready.'
  attachmentFileSystemItemRtIdPath: '$.reportRef.fileSystemRtId'

Eine Datei mit einem menschenlesbaren Dateiname-Override anhängen​

Wenn das FileSystemItem mit einem GUID-artigen Namen gespeichert wurde, die Pipeline aber aus vorgelagerten Metadaten einen besseren Namen kennt, überschreiben Sie ihn beim Senden.

transformations:
- type: ToDiscord@1
  description: Send invoice PDF with its issuer/invoice-number as the filename
  serverConfiguration: discord-main
  channelId: '123456789012345678'
  content: 'New invoice flagged for review.'
  attachmentFileSystemItemRtIdPath: '$.invoice.fileSystemItemRtId'
  attachmentFilenamePath: '$.invoice.readableName'  # e.g. "DemoEnergie-inv-20250930-abc.pdf"

Hinweise​

  • Rate-Limits (HTTP 429) werden als Fehler behandelt; die Exception enthält die von Discord bereitgestellten Retry-After-Sekunden. Der Pipeline-Orchestrator ist für Retry/Backoff verantwortlich.
  • Der Bot-Token erscheint niemals in der Log-Ausgabe oder in Exception-Meldungen — nur im ausgehenden Header Authorization: Bot {token}.
  • Der Node verwendet den benannten HttpClient "Discord", unverändert (keine Polly-Richtlinien in v1).