Freigeben über

Schnellstart: Hinzufügen von Chatfunktionen zu Ihrer App

  • Artikel

Steigen Sie in Azure Communication Services ein, indem Sie das Communication Services Chat SDK nutzen, um Ihre Anwendung mit Echtzeitchatfunktionen zu versehen. In dieser Schnellstartanleitung wird das Chat SDK verwendet, um Chatthreads zu erstellen, die es Benutzern ermöglichen, miteinander zu kommunizieren. Weitere Informationen zu Chatkonzepten finden Sie in der Dokumentation zu Chatkonzepten.

Voraussetzungen

  • Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.

  • Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.

  • Installieren Sie die Azure-Befehlszeilenschnittstelle.

  • Notieren Sie sich den Endpunkt Ihrer Communication Services-Ressource. Sie können den Endpunkt im Azure-Portal abrufen. Alternativ finden Sie die Endpunkt-URL in der Verbindungszeichenfolge. Es handelt sich um die URL, die nach endpoint= folgt und mit https:// beginnt.

  • Ein Benutzerzugriffstoken. Legen Sie den Bereich auf Chat fest und notieren Sie sich die Tokenzeichenfolge und die userId-Zeichenfolge. Sie können auch die Azure CLI verwenden und den folgenden Befehl mit Ihrer Verbindungszeichenfolge ausführen, um einen Benutzer und ein Zugriffstoken zu erstellen.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Ausführliche Informationen finden Sie unter Verwenden der Azure CLI zum Erstellen und Verwalten von Zugriffstoken.

Einrichten

Hinzufügen der Erweiterung

Fügen Sie die Azure Communication Services-Erweiterung für Azure CLI mithilfe des Befehls az extension hinzu.

az extension add --name communication

Anmelden bei der Azure-Befehlszeilenschnittstelle

Sie müssen sich bei Azure CLI anmelden. Sie können sich beim Ausführen des az login-Befehls vom Terminal anmelden und Ihre Anmeldeinformationen bereitstellen.

(Optional) Verwenden von Azure CLI-Identitätsvorgängen ohne Übergabe eines Endpunkts oder Zugriffstokens

Speichern des Endpunkts in einer Umgebungsvariable

Sie können die Umgebungsvariable AZURE_COMMUNICATION_ENDPOINT so konfigurieren, dass Azure CLI-Chatvorgänge verwendet werden, ohne dass Sie --endpoint zum Übergeben des Endpunkts verwenden müssen. Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <yourEndpoint> durch Ihren tatsächlichen Endpunkt.

Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariable gelesen werden muss, z.B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Speichern des Zugriffstokens in einer Umgebungsvariable

Sie können die Umgebungsvariable AZURE_COMMUNICATION_ACCESS_TOKEN so konfigurieren, dass Azure CLI-Chatvorgänge verwendet werden, ohne dass Sie --access-token zum Übergeben des Zugriffstokens verwenden müssen. Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <yourAccessToken> durch Ihr eigentliches Zugriffstoken.

Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariable gelesen werden muss, z.B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Operations

Starten eines Chatthreads

Verwenden Sie den Befehl thread create, um einen Chatthread zu erstellen.

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

Wenn Sie den Endpunkt und das Zugriffstoken wie oben beschrieben in Umgebungsvariablen gespeichert haben, ist eine Übergabe an den Befehl nicht erforderlich.

az communication chat thread create --topic "<chatTopic>"
  • Verwenden Sie <chatTopic>, um für den Thread ein Thema anzugeben. Sie können das Thema nach der Erstellung des Chatthreads aktualisieren, indem Sie den Befehl thread update-topic verwenden.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Aktualisieren des Themas eines Chatthreads

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Ersetzen Sie <chatTopic> durch das neue Chatthema, das Sie festlegen möchten.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Auflisten aller Chatthreads

Der Befehl thread list gibt die Liste der Chatthreads eines Benutzers zurück.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Verwenden Sie optional <startTime>, um den frühesten Zeitpunkt zum Abrufen von Chatnachrichten anzugeben.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Senden einer Nachricht an einen Chatthread

Verwenden Sie den Befehl message send, um eine Nachricht an einen von Ihnen erstellten Chatthread zu senden, der mit threadId gekennzeichnet ist.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Verwenden Sie <content>, um den Inhalt der Chatnachricht anzugeben.
  • Verwenden Sie <messageType>, um den Inhaltstyp der Nachricht anzugeben. Mögliche Werte sind text und html. Wenn Sie keinen Wert angeben, ist der Standardwert text.
  • Verwenden Sie optional <displayName>, um den Anzeigenamen des Absenders anzugeben.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Liste der Chatnachrichten in einem Chatthread

Der Befehl message list gibt die Liste der Chatnachrichten in einem Chatthread zurück.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Verwenden Sie optional <startTime>, um den frühesten Zeitpunkt zum Abrufen von Chatnachrichten anzugeben.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Empfangen einer Chatnachricht aus einem Chatthread

Sie können Chatnachrichten mithilfe des Befehls message list abrufen.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Ersetzen Sie <messageId> durch die ID der Nachricht, die Sie abrufen möchten.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Senden einer Lesebestätigung

Sie verwenden den Befehl message receipt send, um ein Lesebestätigungsereignis im Namen eines Benutzers an einen Thread zu senden.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Ersetzen Sie <messageId>, um die ID der letzten vom aktuellen Benutzer gelesenen Nachricht anzugeben.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Beim Erstellen eines Chatthreads können Sie dafür Benutzer hinzufügen und entfernen. Durch Hinzufügen von Benutzern gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Chatthread und zum Hinzufügen oder Entfernen anderer Teilnehmer. Vergewissern Sie sich vor dem Aufrufen des Befehls participant add, dass Sie über ein neues Zugriffstoken und über eine Identität für den Benutzer verfügen.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Ersetzen Sie <userId> durch Ihre Benutzer-ID.
  • Verwenden Sie optional <displayName>, um den Anzeigenamen des Absenders anzugeben.
  • Verwenden Sie optional <startTime>, um den frühesten Zeitpunkt zum Abrufen von Chatnachrichten anzugeben.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Liste der Threadteilnehmer eines Chatthreads

Threadteilnehmer können aufgelistet werden. Die Vorgehensweise ist dabei ähnlich wie beim Hinzufügen.

Verwenden Sie den Befehl participant list, um die Teilnehmer des Threads abzurufen.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Verwenden Sie optional <skip>, um die Teilnehmer bis zur angegebenen Position in der Antwort zu überspringen.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Entfernen eines Teilnehmers aus einem Chatthread

Sie können einen Chatteilnehmer aus einem Chatthread entfernen, indem Sie den Befehl „participant remove“ verwenden.

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersetzen Sie <chatThreadId> durch Ihre Chatthread-ID.
  • Ersetzen Sie <userId> durch die userId, die Sie aus dem Chatthread entfernen möchten.
  • Ersetzen Sie <endpoint> durch Ihren Azure Communication Services-Endpunkt.
  • Ersetzen Sie <token> durch Ihr Zugriffstoken, das Sie zuvor durch Ausführen des Befehls identity token issue abgerufen haben.

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

  • Erstellen Sie ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie auf der Seite zum Erstellen eines kostenloses Azure-Kontos.

  • Installieren Sie die Active LTS- und Maintenance LTS-Versionen von Node.js.

  • Erstellen Sie eine Azure Communication Services-Ressource. Ausführlichere Informationen hierzu finden Sie unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Sie müssen den Endpunkt und die Verbindungszeichenfolge Ihrer Ressource für diese Schnellstartanleitung aufzeichnen.

  • Erstellen Sie drei Azure Communication Services-Benutzer und stellen Sie Ihnen ein Benutzerzugriffstoken aus. Legen Sie den Bereich auf Chat fest und notieren Sie sich die Tokenzeichenfolge und die userId-Zeichenfolge. In der vollständigen Demo wird ein Thread mit zwei Teilnehmern erstellt und dann ein dritter Teilnehmer hinzugefügt. Sie können auch die Azure CLI verwenden und den folgenden Befehl mit Ihrer Verbindungszeichenfolge ausführen, um einen Benutzer und ein Zugriffstoken zu erstellen.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Ausführliche Informationen finden Sie unter Verwenden der Azure CLI zum Erstellen und Verwalten von Zugriffstoken.

Einrichten

Erstellen einer neuen Webanwendung

Öffnen Sie zunächst Ihr Terminal- bzw. Befehlsfenster, erstellen Sie ein neues Verzeichnis für Ihre App, und greifen Sie auf das Verzeichnis zu.

mkdir chat-quickstart && cd chat-quickstart

Führen Sie npm init -y aus, um die Datei package.json mit den Standardeinstellungen zu erstellen.

npm init -y

Installieren der Pakete

Verwenden Sie den Befehl npm install, um die unten angegebenen Communication Services-SDKs für JavaScript zu installieren.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

Durch die Option --save wird die Bibliothek als Abhängigkeit in der Datei package.json aufgeführt.

Einrichten des App-Frameworks

In diesem Schnellstart wird parcel verwendet, um die Anwendungsressourcen zu bündeln. Führen Sie den folgenden Befehl aus, um das Tool zu installieren und als Entwicklungsabhängigkeit in Ihre Datei package.json aufzunehmen:

npm install parcel --save-dev

Erstellen Sie im Stammverzeichnis Ihres Projekts die Datei index.html. Wir verwenden diese Datei als Vorlage zum Hinzufügen der Chatfunktion mit dem JavaScript-SDK für Chats von Azure Communication Services.

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./client.js" type="module"></script>
  </body>
</html>

Erstellen Sie im Stammverzeichnis Ihres Projekts eine Datei mit dem Namen client.js, die die Anwendungslogik für diese Schnellstartanleitung enthalten soll.

Erstellen eines Chatclients

Zum Erstellen eines Chatclients in Ihrer Web-App benötigen Sie den Communication Services-Endpunkt und das Zugriffstoken, das im Rahmen der Vorbereitung generiert wurde.

Mit Benutzerzugriffstoken können Sie Clientanwendungen erstellen, die gegenüber Azure Communication Services direkt authentifiziert werden. Die Erstellung einer Dienstebene zum Verwalten von Token für Ihre Chatanwendung wird in dieser Schnellstartanleitung nicht behandelt. Unter Chatkonzepte finden Sie weitere Informationen zur Chatarchitektur und unter Benutzerzugriffstoken weitere Informationen zu Zugriffstoken.

Verwenden Sie in client.js den Endpunkt und das Zugriffstoken im folgenden Code, um Chatfunktionen über das JavaScript-SDK für Chats von Azure Communication Services hinzuzufügen.


import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');

Ausführen des Codes

Führen Sie als Nächstes den folgenden Befehl aus, um die App auszuführen:

npx parcel index.html

Navigieren Sie in Ihrem Browser zu http://localhost:1234/.. In Ihrem Browser in der Konsole mit den Entwicklertools sollte Folgendes angezeigt werden:

Azure Communication Chat client created!

Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features des JavaScript-SDKs für Chats von Azure Communication Services verwendet.

name Beschreibung
ChatClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads sowie zum Abonnieren von Chatereignissen.
ChatThreadClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie rufen eine Instanz über den ChatClient ab und verwenden sie zum Senden/Empfangen/Aktualisieren/Löschen von Nachrichten, Hinzufügen/Entfernen/Abrufen von Benutzern und Senden von Eingabebenachrichtigungen und Lesebestätigungen.

Starten eines Chatthreads

Verwenden Sie die createThread-Methode, um einen Chatthread zu erstellen.

createThreadRequest wird zum Beschreiben der Threadanforderung verwendet:

  • Verwenden Sie topic, um für diesen Chat ein Thema anzugeben. Themen können nach der Erstellung des Chatthreads mit der Funktion UpdateThread aktualisiert werden.
  • Verwenden Sie participants, um die Teilnehmer aufzulisten, die dem Chatthread hinzugefügt werden sollen.

Nach der Auflösung wird von der Methode createChatThread eine Antwort vom Typ CreateChatThreadResult zurückgegeben. Dieses Modell enthält eine Eigenschaft vom Typ chatThread. Dort können Sie auf die ID (id) des neu erstellten Threads zugreifen. Mithilfe der ID (id) können Sie anschließend eine Instanz eines Chatthreadclients (ChatThreadClient) abrufen. Mit dem Chatthreadclient (ChatThreadClient) können dann innerhalb des Threads Vorgänge wie das Senden von Nachrichten oder das Auflisten von Teilnehmer ausgeführt werden.

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

Wenn Sie Ihren Browsertab aktualisieren, sollte in der Konsole Folgendes angezeigt werden:

Thread created: <thread_id>

Abrufen eines Clients für den Chatthread

Die getChatThreadClient-Methode gibt einen chatThreadClient für einen bereits vorhandenen Thread zurück. Er kann verwendet werden, um Vorgänge wie das Hinzufügen von Teilnehmern oder das Senden einer Nachricht im erstellten Thread auszuführen. „threadId“ ist die eindeutige ID des vorhandenen Chatthreads.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

Fügen Sie diesen Code anstelle des Kommentars <CREATE CHAT THREAD CLIENT> in client.js hinzu, aktualisieren Sie Ihre Browserregisterkarte, und sehen Sie in Ihrer Konsole nach. Folgendes sollte angezeigt werden:

Chat Thread client for threadId: <threadId>

Auflisten aller Chatthreads

Die Methode listChatThreads gibt ein PagedAsyncIterableIterator von Typ ChatThreadItem zurück. Sie kann zum Auflisten aller Chatthreads verwendet werden. Beim Auflisten von Threads wird als Antwort ein Iterator vom Typ [ChatThreadItem] zurückgegeben.

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

Senden einer Nachricht an einen Chatthread

Verwenden Sie die sendMessage-Methode, um eine Nachricht an einen Thread zu senden, der mit der „threadId“ identifiziert wird.

sendMessageRequest wird verwendet, um die Nachrichtenanforderung zu beschreiben:

  • Verwenden Sie content, um den Inhalt der Chatnachricht anzugeben.

sendMessageOptions wird verwendet, um die optionalen Vorgangsparameter zu beschreiben:

  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben.
  • Verwenden Sie type, um den Nachrichtentyp anzugeben, etwa Text oder HTML.
  • Verwenden Sie optional metadata, um alle zusätzlichen Daten einzubeziehen, die Sie zusammen mit der Nachricht senden möchten. Dieses Feld bietet Entwicklern einen Mechanismus, um die Chatnachrichtenfunktionalität zu erweitern und benutzerdefinierte Informationen für Ihren Anwendungsfall hinzuzufügen. Wenn Sie beispielsweise einen Dateilink in der Nachricht freigeben, sollten Sie „hasAttachment:true“ in den Metadaten hinzufügen, damit die Anwendung des Empfängers diese analysieren und entsprechend anzeigen kann.

SendChatMessageResult ist die Antwort, die nach dem Senden einer Nachricht zurückgegeben wird. Sie enthält eine ID, bei der es sich um die eindeutige ID der Nachricht handelt.

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

Fügen Sie diesen Code anstelle des Kommentars <SEND MESSAGE TO A CHAT THREAD> in client.js hinzu, aktualisieren Sie Ihre Browserregisterkarte, und sehen Sie in Ihrer Konsole nach.

Message sent!, message id:<number>

Empfangen von Chatnachrichten aus einem Chatthread

Bei der Echtzeitsignalisierung können Sie eine Funktion abonnieren, mit der auf neue eingehende Nachrichten gelauscht wird und die aktuellen Nachrichten im Arbeitsspeicher entsprechend aktualisiert werden. Azure Communication Services unterstützt eine Liste mit Ereignissen, die Sie abonnieren können.

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

Fügen Sie diesen Code anstelle des Kommentars <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> in client.js hinzu. Wenn Sie die Registerkarte in Ihrem Browser aktualisieren, sollte in der Konsole die Meldung Notification chatMessageReceived angezeigt werden.

Alternativ können Sie Chatnachrichten auch abrufen, indem Sie die listMessages-Methode jeweils nach dem angegebenen Intervallzeitraum abfragen.


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

Fügen Sie diesen Code anstelle des Kommentars <LIST MESSAGES IN A CHAT THREAD> in client.js hinzu. Aktualisieren Sie Ihren Tab. Daraufhin sollte in der Konsole die Liste mit den Nachrichten angezeigt werden, die in diesem Chatthread gesendet wurden.

Mit listMessages werden unterschiedliche Nachrichtentypen zurückgegeben, die mit chatMessage.type identifiziert werden können.

Weitere Details finden Sie unter Nachrichtentypen.

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Nach der Erstellung eines Chatthreads können Sie dafür Benutzer hinzufügen und entfernen. Indem Sie Benutzer hinzufügen, gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Chatthread und zum Hinzufügen/Entfernen anderer Teilnehmer.

Vergewissern Sie sich vor dem Aufrufen der Methode addParticipants, dass Sie über ein neues Zugriffstoken und über eine Identität für den Benutzer verfügen. Der Benutzer benötigt dieses Zugriffstoken, um den Chatclient initialisieren zu können.

addParticipantsRequest dient zum Beschreiben des Anforderungsobjekts, und darin wird participants verwendet, um die hinzuzufügenden Teilnehmer für den Chatthread aufzulisten.

  • id (erforderlich) ist der Kommunikationsbezeichner, der dem Chatthread hinzugefügt werden soll.
  • displayName (optional) ist der Anzeigename für den Threadteilnehmer.
  • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird. Sie können den Verlauf seit dem Beginn des Chatthreads freigeben, indem Sie diese Eigenschaft auf das Datum der Threaderstellung (oder früher) festlegen. Soll der Verlauf vor dem Hinzufügezeitpunkt des Teilnehmers nicht freigegeben werden, geben Sie das aktuelle Datum an. Geben Sie ein Datum Ihrer Wahl an, um einen Teil des Verlaufs freizugeben.

const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

Ersetzen Sie NEW_PARTICIPANT_USER_ID durch eine neue Benutzer-ID. Fügen Sie diesen Code anstelle des Kommentars <ADD NEW PARTICIPANT TO THREAD> in der Datei client.js hinzu.

Auflisten von Benutzern in einem Chatthread

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

Fügen Sie diesen Code anstelle des Kommentars <LIST PARTICIPANTS IN A THREAD> in client.js hinzu, aktualisieren Sie Ihre Browserregisterkarte, und sehen Sie in Ihrer Konsole nach. Es sollten Informationen zu den Benutzern eines Threads angezeigt werden.

Entfernen eines Benutzers aus einem Chatthread

Teilnehmer können auch aus einem Chatthread entfernt werden. Die Vorgehensweise ist dabei ähnlich wie beim Hinzufügen. Zum Entfernen benötigen Sie die IDs der von Ihnen hinzugefügten Teilnehmer.

Verwenden Sie die removeParticipant-Methode. Hierbei ist participant der Kommunikationsbenutzer, der aus dem Thread entfernt werden soll.


await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

Ersetzen Sie PARTICIPANT_ID durch eine Benutzer-ID aus dem vorherigen Schritt (<NEW_PARTICIPANT_USER_ID>). Fügen Sie diesen Code anstelle des Kommentars <REMOVE PARTICIPANT FROM THREAD> in client.js hinzu.

Abonnieren des Verbindungsstatus von Echtzeitbenachrichtigungen

Mit dem Abonnement für die Ereignisse realTimeNotificationConnected und realTimeNotificationDisconnected erfahren Sie, wann die Verbindung mit dem Aufrufserver aktiv ist.

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

Einrichten

Erstellen einer neuen Python-Anwendung

Öffnen Sie Ihr Terminal- oder Befehlsfenster, erstellen Sie ein neues Verzeichnis für Ihre App, und navigieren Sie zu diesem Verzeichnis.

mkdir chat-quickstart && cd chat-quickstart

Verwenden Sie einen Text-Editor, um im Stammverzeichnis des Projekts die Datei start-chat.py zu erstellen. Fügen Sie die Struktur für das Programm hinzu, einschließlich einer einfachen Ausnahmebehandlung In den folgenden Abschnitten fügen Sie der Datei den gesamten Quellcode für diese Schnellstartanleitung hinzu.

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

Installieren des SDK

Verwenden Sie den folgenden Befehl, um das SDK zu installieren:


pip install azure-communication-chat

Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features des Chat-SDKs von Azure Communication Services für Python verwendet.

Name BESCHREIBUNG
ChatClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads.
ChatThreadClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie erhalten über ChatClient eine Instanz und verwenden sie zum Senden, Empfangen, Aktualisieren und Löschen von Nachrichten. Darüber hinaus können Sie sie auch verwenden, um Benutzer hinzuzufügen, zu entfernen und abzurufen sowie Eingabebenachrichtigungen und Lesebestätigungen zu senden.

Erstellen eines Chatclients

Zum Erstellen eines Chatclients verwenden Sie den Communication Services-Endpunkt und das Zugriffstoken, das Sie im Rahmen der Schritte zur Erfüllung der Voraussetzungen generiert haben.

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

Die Erstellung einer Dienstebene zum Verwalten von Token für Ihre Chatanwendung wird in dieser Schnellstartanleitung nicht behandelt, aber dies ist die empfohlene Vorgehensweise. Weitere Informationen finden Sie im Artikel Chatkonzepte im Abschnitt „Chatarchitektur“.

Starten eines Chatthreads

Verwenden Sie die create_chat_thread-Methode, um einen Chatthread zu erstellen.

  • Verwenden Sie topic, um für den Thread ein Thema anzugeben. Sie können das Thema aktualisieren, nachdem der Chatthread mithilfe der Funktion update_thread erstellt wurde.
  • Verwenden Sie thread_participants, um den Chatteilnehmer (ChatParticipant) aufzulisten, der dem Chatthread hinzugefügt werden soll. ChatParticipant übernimmt user als CommunicationUserIdentifier-Typ.

CreateChatThreadResult ist das Ergebnis, das beim Erstellen eines Chatthreads zurückgegeben wird. Sie können es verwenden, um die ID (id) des erstellten Chatthreads abzurufen. Diese ID (id) kann dann zum Abrufen eines ChatThreadClient-Objekts mithilfe der Methode get_chat_thread_client verwendet werden. Mit ChatThreadClient können weitere Chatvorgänge für diesen Chatthread ausgeführt werden.

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

Abrufen eines Clients für den Chatthread

Die get_chat_thread_client-Methode gibt einen Threadclient für einen bereits vorhandenen Thread zurück. Sie können sie verwenden, um weitere Vorgänge für den Chatthread auszuführen. Beispielsweise können Sie Teilnehmer hinzufügen und Nachrichten senden. thread_id ist die eindeutige ID des vorhandenen Chatthreads.

Mit ChatThreadClient können weitere Chatvorgänge für diesen Chatthread ausgeführt werden.

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

Auflisten aller Chatthreads

Von der Methode list_chat_threads wird ein Iterator vom Typ ChatThreadItem zurückgegeben.

  • Verwenden Sie start_time, um den frühesten Zeitpunkt zum Abrufen von Chatthreads anzugeben.
  • Verwenden Sie results_per_page, um die maximale Anzahl von Chatthreads anzugeben, die pro Seite zurückgegeben werden sollen.

Beim Auflisten von Threads wird als Antwort ein Iterator vom Typ [ChatThreadItem] zurückgegeben.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

Senden einer Nachricht an einen Chatthread

Verwenden Sie die send_message-Methode zum Senden einer Nachricht an einen Chatthread, den Sie gerade erstellt haben und der anhand von thread_id identifiziert wird.

  • Verwenden Sie content, um den Inhalt der Chatnachricht anzugeben.
  • Verwenden Sie chat_message_type, um den Inhaltstyp der Nachricht anzugeben. Mögliche Werte sind text und html. Wenn Sie keinen Wert angeben, ist der Standardwert text.
  • Verwenden Sie sender_display_name, um den Anzeigenamen des Absenders anzugeben.
  • Verwenden Sie optional metadata, um alle zusätzlichen Daten einzubeziehen, die Sie zusammen mit der Nachricht senden möchten. Dieses Feld bietet Entwicklern einen Mechanismus, um die Chatnachrichtenfunktionalität zu erweitern und benutzerdefinierte Informationen für Ihren Anwendungsfall hinzuzufügen. Wenn Sie beispielsweise einen Dateilink in der Nachricht freigeben, sollten Sie „hasAttachment:true“ in den Metadaten hinzufügen, damit die Anwendung des Empfängers diese analysieren und entsprechend anzeigen kann.

SendChatMessageResult ist die Antwort, die beim Senden einer Nachricht zurückgegeben wird. Sie enthält eine ID, bei der es sich um die eindeutige ID der Nachricht handelt.

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

Empfangen von Chatnachrichten aus einem Chatthread

Sie können Chatnachrichten abrufen, indem Sie die list_messages-Methode jeweils nach dem angegebenen Intervallzeitraum abfragen.

  • Verwenden Sie results_per_page, um die maximale Anzahl von Nachrichten anzugeben, die pro Seite zurückgegeben werden sollen.
  • Verwenden Sie start_time, um den frühesten Zeitpunkt zum Abrufen von Nachrichten anzugeben.

Beim Auflisten von Nachrichten wird als Antwort ein Iterator vom Typ [ChatMessage] zurückgegeben.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages gibt die aktuelle Version der Nachricht zurück, einschließlich aller Bearbeitungen oder Löschungen, die für die Nachricht mit update_message und delete_message durchgeführt wurden. Für gelöschte Nachrichten wird von ChatMessage.deleted_on ein datetime-Wert zurückgegeben, mit dem der Löschzeitpunkt der Nachricht angegeben wird. Für bearbeitete Nachrichten gibt ChatMessage.edited_on einen datetime-Wert zurück, mit dem der Bearbeitungszeitpunkt der Nachricht angegeben wird. Auf den ursprünglichen Zeitpunkt der Nachrichtenerstellung kann mithilfe von ChatMessage.created_on zugegriffen werden. Dieses Element kann zum Sortieren der Nachrichten genutzt werden.

Mit list_messages werden unterschiedliche Nachrichtentypen zurückgegeben, die mit ChatMessage.type identifiziert werden können.

Weitere Informationen finden Sie unter Nachrichtentypen.

Senden einer Lesebestätigung

Sie können die Methode send_read_receipt verwenden, um im Auftrag eines Benutzers ein Lesebestätigungsereignis in einem Thread zu veröffentlichen.

  • Verwenden Sie message_id, um die ID der letzten vom aktuellen Benutzer gelesenen Nachricht anzugeben.
content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Beim Erstellen eines Chatthreads können Sie dafür Benutzer hinzufügen und entfernen. Durch Hinzufügen von Benutzern gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Chatthread und zum Hinzufügen oder Entfernen anderer Teilnehmer. Vergewissern Sie sich vor dem Aufrufen der Methode add_participants, dass Sie über ein neues Zugriffstoken und über eine Identität für den Benutzer verfügen. Der Benutzer benötigt dieses Zugriffstoken, um den Chatclient initialisieren zu können.

Mithilfe der Methode add_participants können Sie dem Chatthread einen oder mehrere Benutzer hinzufügen, sofern für alle Benutzer ein neues Zugriffstoken und eine neue Identität verfügbar sind.

Ein list(tuple(ChatParticipant, CommunicationError)) wird zurückgegeben. Wenn der Teilnehmer erfolgreich hinzugefügt wurde, wird eine leere Liste erwartet. Tritt beim Hinzufügen eines Teilnehmers ein Fehler auf, wird die Liste mit den Teilnehmern, bei denen ein Fehler auftrat, sowie den aufgetretenen Fehler aufgefüllt.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

Liste der Threadteilnehmer eines Chatthreads

Threadteilnehmer können aufgelistet werden. Die Vorgehensweise ist dabei ähnlich wie beim Hinzufügen.

Verwenden Sie list_participants, um die Teilnehmer des Threads abzurufen. Die beiden folgenden Befehle sind optional:

  • Verwenden Sie results_per_page, um die maximale Anzahl von Teilnehmern anzugeben, die pro Seite zurückgegeben werden sollen.
  • Verwenden Sie skip, um die Teilnehmer bis zur angegebenen Position in der Antwort zu überspringen.

Beim Auflisten von Teilnehmern wird als Antwort ein Iterator vom Typ [ChatParticipant] zurückgegeben.

chat_thread_participants = chat_thread_client.list_participants()
for chat_thread_participant_page in chat_thread_participants.by_page():
    for chat_thread_participant in chat_thread_participant_page:
        print("ChatParticipant: ", chat_thread_participant)

Ausführen des Codes

Führen Sie die Anwendung mit dem Befehl python aus dem Anwendungsverzeichnis aus.

python start-chat.py

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Einrichten

Erstellen einer neuen Java-Anwendung

Öffnen Sie Ihr Terminal- oder Befehlsfenster, und navigieren Sie zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den unten angegebenen Befehl aus, um das Java-Projekt aus der Vorlage „maven-archetype-quickstart“ zu generieren.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Sie sehen, dass über das Ziel „generate“ ein Verzeichnis mit dem gleichen Namen wie für die „artifactId“ erstellt wurde. In diesem Verzeichnis enthält src/main/java directory den Quellcode des Projekts, das Verzeichnis src/test/java enthält die Testquelle, und die Datei „pom.xml“ ist das Projektobjektmodell (POM) des Projekts.

Aktualisieren Sie die POM-Datei Ihrer Anwendung für die Verwendung von Java 8 oder höher:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Hinzufügen der Paketverweise für das Chat-SDK

Verweisen Sie in Ihrer POM-Datei auf das Paket azure-communication-chat mit den Chat-APIs:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

Für die Authentifizierung muss Ihr Client auf das Paket azure-communication-common verweisen:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features des Chat-SDKs von Azure Communication Services für Java verwendet.

Name Beschreibung
ChatClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads.
ChatAsyncClient Diese Klasse wird für die asynchrone Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads.
ChatThreadClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie rufen eine Instanz über den ChatClient ab und verwenden sie zum Senden/Empfangen/Aktualisieren/Löschen von Nachrichten, Hinzufügen/Entfernen/Abrufen von Benutzern und Senden von Eingabebenachrichtigungen und Lesebestätigungen.
ChatThreadAsyncClient Diese Klasse wird für die asynchrone Chatthreadfunktionalität benötigt. Sie rufen eine Instanz über den ChatAsyncClient ab und verwenden sie zum Senden/Empfangen/Aktualisieren/Löschen von Nachrichten, Hinzufügen/Entfernen/Abrufen von Benutzern und Senden von Eingabebenachrichtigungen und Lesebestätigungen.

Erstellen eines Chatclients

Zum Erstellen eines Chatclients verwenden Sie den Communication Services-Endpunkt und das Zugriffstoken, das im Rahmen der Schritte zur Erfüllung der Voraussetzungen generiert wurde. Mit Benutzerzugriffstoken können Sie Clientanwendungen erstellen, die gegenüber Azure Communication Services direkt authentifiziert werden. Nachdem Sie diese Token auf Ihrem Server generiert haben, übergeben Sie sie zurück an ein Clientgerät. Sie müssen die Klasse „CommunicationTokenCredential“ aus dem allgemeinen SDK verwenden, um das Token an Ihren Chatclient zu übergeben.

Weitere Informationen zur Chatarchitektur

Achten Sie beim Hinzufügen der Importanweisungen darauf, nur Importe aus den Namespaces „com.azure.communication.chat“ und „com.azure.communication.chat.models“ hinzuzufügen (nicht aus dem Namespace „com.azure.communication.chat.implementation“). In der Datei „App.java“, die über Maven generiert wurde, können Sie den folgenden Code verwenden, um zu beginnen:

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

Starten eines Chatthreads

Verwenden Sie die createChatThread-Methode, um einen Chatthread zu erstellen. createChatThreadOptions wird zum Beschreiben der Threadanforderung verwendet.

  • Verwenden Sie topic des Konstruktors, um für diesen Chat ein Thema anzugeben. Nach dem Erstellen des Chatthreads kann das Thema mit der Funktion UpdateThread aktualisiert werden.
  • Verwenden Sie participants, um die Threadteilnehmer aufzulisten, die dem Thread hinzugefügt werden sollen. Für ChatParticipant wird der Benutzer verwendet, den Sie in der Schnellstartanleitung Benutzerzugriffstoken erstellt haben.

CreateChatThreadResult ist die Antwort, die beim Erstellen eines Chatthreads zurückgegeben wird. Sie enthält eine Methode getChatThread(), die das Objekt ChatThread zurückgibt. Mit diesem kann der Threadclient abgerufen werden, aus dem Sie den ChatThreadClient zum Ausführen von Vorgängen mit dem erstellten Thread erhalten: Hinzufügen von Teilnehmern, Senden einer Nachricht usw. Das ChatThread-Objekt enthält zudem die Methode getId(), die die eindeutige ID des Threads abruft.

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

Auflisten von Chatthreads

Verwenden Sie die Methode listChatThreads, um eine Liste vorhandener Chatthreads abzurufen.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

Abrufen eines Clients für den Chatthread

Die getChatThreadClient-Methode gibt einen Threadclient für einen bereits vorhandenen Thread zurück. Er kann verwendet werden, um Vorgänge wie das Hinzufügen von Teilnehmern oder das Senden einer Nachricht im erstellten Thread auszuführen. chatThreadId ist die eindeutige ID des vorhandenen Chatthreads.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Senden einer Nachricht an einen Chatthread

Verwenden Sie die Methode sendMessage zum Senden einer Nachricht an den soeben von Ihnen erstellten Thread, der anhand der „chatThreadId“ identifiziert wird. sendChatMessageOptions wird verwendet, um die Anforderung der Chatnachricht zu beschreiben.

  • Verwenden Sie content, um den Inhalt der Chatnachricht anzugeben.
  • Verwenden Sie type, um den Inhaltstyp der Chatnachricht (Text oder HTML) anzugeben.
  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben.
  • Verwenden Sie optional metadata, um alle zusätzlichen Daten einzubeziehen, die Sie zusammen mit der Nachricht senden möchten. Dieses Feld bietet Entwicklern einen Mechanismus, um die Chatnachrichtenfunktionalität zu erweitern und benutzerdefinierte Informationen für Ihren Anwendungsfall hinzuzufügen. Wenn Sie beispielsweise einen Dateilink in der Nachricht teilen, sollten Sie hasAttachment:true in die Metadaten einfügen, damit die Anwendung des Empfängers diese analysieren und entsprechend anzeigen kann.

Die Antwort sendChatMessageResult enthält eine id, bei der es sich um die eindeutige ID der Nachricht handelt.

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

Empfangen von Chatnachrichten aus einem Chatthread

Sie können Chatnachrichten abrufen, indem Sie die listMessages-Methode auf dem Chatthreadclient jeweils nach dem angegebenen Intervallzeitraum abfragen.

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages gibt die aktuelle Version der Nachricht zurück, einschließlich aller Bearbeitungen oder Löschungen, die für die Nachricht mit .editMessage() und .deleteMessage() durchgeführt wurden. Für gelöschte Nachrichten wird von chatMessage.getDeletedOn() ein datetime-Wert zurückgegeben, mit dem der Löschzeitpunkt der Nachricht angegeben wird. Für bearbeitete Nachrichten gibt chatMessage.getEditedOn() einen datetime-Wert zurück, mit dem der Bearbeitungszeitpunkt der Nachricht angegeben wird. Auf den ursprünglichen Zeitpunkt der Nachrichtenerstellung kann mit chatMessage.getCreatedOn() zugegriffen werden. Dieses Element kann zum Sortieren der Nachrichten genutzt werden.

Weitere Informationen zu Nachrichtentypen finden Sie hier: Nachrichtentypen.

Senden einer Lesebestätigung

Die Methode sendReadReceipt kann verwendet werden, um im Auftrag eines Benutzers ein Lesebestätigungsereignis in einem Thread zu veröffentlichen. chatMessageId ist die eindeutige ID der Chatnachricht, die gelesen wurde.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

Auflisten von Chatteilnehmern

Verwenden Sie listParticipants, um eine in Seiten eingeteilte Sammlung mit den Teilnehmern des mit der chatThreadId identifizierten Chatthreads abzurufen.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Nach der Erstellung eines Chatthreads können Sie dafür Benutzer hinzufügen und entfernen. Indem Sie Benutzer hinzufügen, gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Chatthread und zum Hinzufügen/Entfernen anderer Teilnehmer. Zunächst müssen Sie ein neues Zugriffstoken und eine Identität für den Benutzer abrufen. Stellen Sie vor dem Aufrufen der addParticipants-Methode sicher, dass Sie ein neues Zugriffstoken und eine Identität für den Benutzer abgerufen haben. Der Benutzer benötigt dieses Zugriffstoken, um den Chatclient initialisieren zu können.

Verwenden Sie die Methode addParticipants zum Hinzufügen von Teilnehmern zum Thread.

  • communicationIdentifier (erforderlich) ist das CommunicationIdentifier-Element, das Sie mit „CommunicationIdentityClient“ in der Schnellstartanleitung Benutzerzugriffstoken erstellt haben.
  • displayName (optional) ist der Anzeigename für den Threadteilnehmer.
  • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird. Sie können den Verlauf seit dem Beginn des Chatthreads freigeben, indem Sie diese Eigenschaft auf das Datum der Threaderstellung (oder früher) festlegen. Soll der Verlauf vor dem Hinzufügezeitpunkt des Teilnehmers nicht freigegeben werden, geben Sie das aktuelle Datum an. Geben Sie ein gewünschtes Datum an, um nur einen Teil des Verlaufs freizugeben.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

Ausführen des Codes

Navigieren Sie zum Verzeichnis, das die Datei pom.xml enthält, und kompilieren Sie das Projekt mit dem folgenden mvn-Befehl.

mvn compile

Erstellen Sie dann das Paket.

mvn package

Führen Sie die App mit dem folgenden mvn-Befehl aus.

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

  • Erstellen Sie ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie auf der Seite zum Erstellen eines kostenloses Azure-Kontos.

  • Installieren Sie Android Studio. Damit erstellen Sie in diesem Schnellstart eine Android-Anwendung zum Installieren von Abhängigkeiten.

  • Erstellen Sie eine Azure Communication Services-Ressource. Ausführlichere Informationen hierzu finden Sie unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Sie müssen den Endpunkt und die Verbindungszeichenfolge Ihrer Ressource für diese Schnellstartanleitung aufzeichnen.

  • Erstellen Sie zwei Communication Services-Benutzer und stellen Sie Ihnen Benutzerzugriffstoken aus. Stellen Sie sicher, dass Sie als Bereich Chat festlegen, und notieren Sie sich die Tokenzeichenfolge und die userId-Zeichenfolge. In diesem Schnellstart erstellen Sie einen Thread mit einem Teilnehmer und fügen anschließend einen zweiten Teilnehmer hinzu. Sie können auch die Azure CLI verwenden und den folgenden Befehl mit Ihrer Verbindungszeichenfolge ausführen, um einen Benutzer und ein Zugriffstoken zu erstellen.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Ausführliche Informationen finden Sie unter Verwenden der Azure CLI zum Erstellen und Verwalten von Zugriffstoken.

Einrichten

Erstellen einer neuen Android-Anwendung

  1. Öffnen Sie Android Studio, und klicken Sie auf Create a new project (Neues Projekt erstellen).
  2. Wählen Sie im nächsten Fenster die Projektvorlage Empty Activity (Leere Aktivität) aus.
  3. Geben Sie bei der Auswahl der Optionen ChatQuickstart als Projektnamen ein.
  4. Klicken Sie auf „Weiter“, und wählen Sie das Verzeichnis aus, in dem Sie das Projekt erstellen möchten.

Installieren der Bibliotheken

Für die Installation der erforderlichen Communication Services-Abhängigkeiten wird in diesem Schnellstart Gradle verwendet. Navigieren Sie in der Befehlszeile zum Stammverzeichnis des Projekts ChatQuickstart. Öffnen Sie die Datei „build.gradle“ der App, und fügen Sie die folgenden Abhängigkeiten für das ChatQuickstart-Ziel hinzu:

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

Die aktuellen Versionsnummern finden Sie unter https://search.maven.org/artifact/com.azure.android/azure-communication-common und https://search.maven.org/artifact/com.azure.android/azure-communication-chat.

Ausschließen von Metadatendateien in den Paketoptionen der Stammdatei „build.gradle“

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

(Alternative) So installieren Sie Bibliotheken über Maven

Wenn Sie die Bibliothek über das Maven-Buildsystem in Ihr Projekt importieren möchten, fügen Sie sie in der Datei pom.xml Ihrer App im Abschnitt dependencies hinzu, und geben Sie dabei die Artefakt-ID und die Version an, die Sie verwenden möchten:

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

Einrichten von Azure Functions

Weitere Informationen finden Sie unter Azure Function-Integration. Die Integration von Azure Function wird dringend empfohlen, um die Hartcodierung von Anwendungsparametern zu vermeiden.

Richten Sie Anwendungskonstanten ein:

Erstellen Sie eine Klasse ApplicationConstants, in der alle Anwendungskonstanten gespeichert werden:

public class ApplicationConstants {
    public static final String SDK_VERSION = "<your_version>";
    public final static String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    public final static String APPLICATION_ID = "Chat_Test_App";
    public final static String TAG = "[Chat Test App]";
    public static CommunicationTokenCredential COMMUNICATION_TOKEN_CREDENTIAL;
}

Einrichten der Platzhalter

Öffnen Sie die Datei MainActivity.java, und bearbeiten Sie sie. In diesem Schnellstart fügen Sie den Code zu MainActivity hinzu und sehen sich die Ausgabe in der Konsole an. Das Erstellen einer Benutzeroberfläche wird in dieser Schnellstartanleitung nicht behandelt. Importieren Sie am Anfang der Datei Azure Communication Common, Azure Communication Chat und andere Systembibliotheken:

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

Kopieren Sie in der Datei MainActivity.java den folgenden Code in die Klasse MainActivity:

    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Log.i(TAG, msg);
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // Initialize application parameters if one of the conditions in '### Initialize Application Parameters' are met.

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }

Initialisieren von Anwendungsparametern

Hinweis

Die Initialisierung von ApplicationConstants muss zu MainActivity.java hinzugefügt werden, wenn EINE der folgenden Bedingungen erfüllt ist: 1. Die Pushbenachrichtigungsfunktion ist NICHT aktiviert. 2. Die Version der Azure Communication Chat-Bibliothek für Android ist < „2.0.0“. Lesen Sie andernfalls Schritt 11 in Android-Pushbenachrichtigungen. Weitere Informationen finden Sie in der Beispiel-APP der von Ihnen verwendeten SDK-Version.

ACS_ENDPOINT, FIRST_USER_ID und FIRST_USER_ACCESS_TOKEN werden vom Aufruf von Azure Function zurückgegeben. Weitere Informationen finden Sie unter Azure Function-Integration. Wir verwenden die Antwort vom Aufruf von Azure Function, um die Parameterliste zu initialisieren:

  • ACS_ENDPOINT: der Endpunkt Ihrer Communication Services-Ressource.
  • FIRST_USER_ID und SECOND_USER_ID: gültige Communication Services-Benutzer-IDs, die von Ihrer Communication Services-Ressource generiert wurden.
  • FIRST_USER_ACCESS_TOKEN: das Communication Services-Zugriffstoken für <FIRST_USER_ID>.

Codeblock zum Initialisieren von Anwendungsparametern durch Aufruf von Azure Function:

try {
        UserTokenClient userTokenClient = new UserTokenClient(AZURE_FUNCTION_URL);
        //First user context
        userTokenClient.getNewUserContext();
        ACS_ENDPOINT = userTokenClient.getACSEndpoint();
        FIRST_USER_ID = userTokenClient.getUserId();
        FIRST_USER_ACCESS_TOKEN = userTokenClient.getUserToken();
        COMMUNICATION_TOKEN_CREDENTIAL = new CommunicationTokenCredential(FIRST_USER_ACCESS_TOKEN);
        //Second user context
        userTokenClient.getNewUserContext();
        SECOND_USER_ID = userTokenClient.getUserId();
    } catch (Throwable throwable) {
        //Your handling code
        logger.logThrowableAsError(throwable);
    }

Erstellen eines Chatclients

Ersetzen Sie den Kommentar <CREATE A CHAT CLIENT> durch den folgenden Code (fügen Sie die Importanweisungen oben in der Datei ein):

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features des JavaScript-SDKs für Chats von Azure Communication Services verwendet.

name BESCHREIBUNG
ChatClient/ChatAsyncClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads sowie zum Abonnieren von Chatereignissen.
ChatThreadClient/ChatThreadAsyncClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie rufen eine Instanz über den ChatClient ab und verwenden sie zum Senden/Empfangen/Aktualisieren/Löschen von Nachrichten, Hinzufügen/Entfernen/Abrufen von Benutzern und Senden von Eingabebenachrichtigungen und Lesebestätigungen.

Starten eines Chatthreads

Mit ChatAsyncClient erstellen Sie einen neuen Thread mit zunächst einem Benutzer.

Ersetzen Sie den Kommentar <CREATE A CHAT THREAD> durch folgenden Code:

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

Abrufen eines Clients für den Chatthread

Nachdem Sie nun einen Chatthread erstellt haben, rufen Sie als Nächstes einen Chatthreadclient (ChatThreadAsyncClient) ab, um in diesem Thread Vorgänge ausführen zu können. Ersetzen Sie den Kommentar <CREATE A CHAT THREAD CLIENT> durch folgenden Code:

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

Senden einer Nachricht an einen Chatthread

Als Nächstes wird eine Nachricht an diesen Thread gesendet.

Ersetzen Sie den Kommentar <SEND A MESSAGE> durch folgenden Code:

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

Empfangen von Chatnachrichten aus einem Chatthread

Echtzeitbenachrichtigungen

Bei der Echtzeitsignalisierung können Sie neue eingehende Nachrichten abonnieren und die aktuellen Nachrichten im Arbeitsspeicher entsprechend aktualisiert. Azure Communication Services unterstützt eine Liste mit Ereignissen, die Sie abonnieren können.

Ersetzen Sie den Kommentar <RECEIVE CHAT MESSAGES> durch den folgenden Code (fügen Sie die Importanweisungen oben in der Datei ein):


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

Wichtig

Bekanntes Problem: Bei gemeinsamer Verwendung von Android Chat und Calling SDK in der gleichen Anwendung funktioniert das Echtzeitbenachrichtigungsfeature des Chat SDK nicht. Möglicherweise tritt ein Problem beim Auflösen der Abhängigkeit auf. Wir arbeiten bereits an einer Lösung. Bis diese zur Verfügung steht, können Sie das Echtzeitbenachrichtigungsfeature deaktivieren, indem Sie in der Datei „build.gradle“ der App die folgenden Abhängigkeitsinformationen hinzufügen und stattdessen die GetMessages-API abfragen, um eingehende Nachrichten für Benutzer anzuzeigen:

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

Beachten Sie, dass bei der obigen Aktualisierung ein Laufzeitfehler auftritt, wenn die Anwendung versucht, eine der Benachrichtigungs-APIs (etwa chatAsyncClient.startRealtimeNotifications() oder chatAsyncClient.addEventHandler()) zu verwenden.

Pushbenachrichtigungen

Weitere Informationen finden Sie unter Android-Pushbenachrichtigungen.

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Ersetzen Sie den Kommentar <ADD A USER> durch folgenden Code:

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

Auflisten der Benutzer in einem Thread

Ersetzen Sie den Kommentar <LIST USERS> durch den folgenden Code. (Platzieren Sie die Importanweisungen am Anfang der Datei.)

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

Entfernen eines Benutzers aus einem Chatthread

In diesem Abschnitt wird der zweite Benutzer aus dem Thread entfernt.

Ersetzen Sie den <REMOVE A USER>-Kommentar durch folgenden Code:

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

Senden einer Tippbenachrichtigung

Ersetzen Sie den <SEND A TYPING NOTIFICATION>-Kommentar durch folgenden Code:

chatThreadAsyncClient.sendTypingNotification().get();

Senden einer Lesebestätigung

Wir senden eine Lesebestätigung für die oben gesendete Nachricht.

Ersetzen Sie den <SEND A READ RECEIPT>-Kommentar durch folgenden Code:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Auflisten von Lesebestätigungen

Ersetzen Sie den <READ RECEIPTS>-Kommentar durch folgenden Code:

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

Ausführen des Codes

Klicken Sie in Android Studio auf die Schaltfläche „Run“ (Ausführen), um das Projekt zu erstellen und auszuführen. In der Konsole können Sie sich die Ausgabe des Codes sowie die Protokollierungsausgabe des Chatclients ansehen.

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

Einrichten

Erstellen einer neuen C#-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen ChatQuickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.

dotnet new console -o ChatQuickstart

Wechseln Sie zum neu erstellten App-Ordner, und verwenden Sie den Befehl dotnet build, um Ihre Anwendung zu kompilieren.

cd ChatQuickstart
dotnet build

Installieren des Pakets

Installieren des .NET SDK für Chats von Azure Communication Services

dotnet add package Azure.Communication.Chat

Objektmodell

Die folgenden Klassen werden für einige der wichtigsten Features des C#-SDK für Chats von Azure Communication Services verwendet.

name Beschreibung
ChatClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads.
ChatThreadClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie rufen eine Instanz über den Chatclient ab und verwenden sie zum Senden/Empfangen/Aktualisieren/Löschen von Nachrichten, zum Hinzufügen/Entfernen/Abrufen von Teilnehmern und zum Senden von Eingabebenachrichtigungen und Lesebestätigungen.

Erstellen eines Chatclients

Zum Erstellen eines Chatclients verwenden Sie Ihren Communication Services-Endpunkt und das Zugriffstoken, das im Rahmen der erforderlichen Schritte zur Vorbereitung generiert wurde. Sie müssen die CommunicationIdentityClient-Klasse über das Identitäts-SDK verwenden, um einen Benutzer zu erstellen und ein Token auszustellen, das Sie an Ihren Chatclient übergeben können.

Informieren Sie sich über Benutzerzugriffstoken.

Die Erstellung einer Dienstebene zum Verwalten von Token für Ihre Chatanwendung wird empfohlen, wird aber in diesem Schnellstart nicht behandelt. Weitere Informationen zur Chatarchitektur finden Sie hier.

Kopieren Sie die folgenden Codeausschnitte, und fügen Sie sie in die Quelldatei Program.cs ein:

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Starten eines Chatthreads

Verwenden Sie die Methode createChatThread für den Chatclient, um einen Chatthread zu erstellen.

  • Verwenden Sie topic, um für diesen Chat ein Thema anzugeben. Nach der Erstellung des Chatthreads kann das Thema mit der Funktion UpdateTopic aktualisiert werden.
  • Verwenden Sie die participants-Eigenschaft zum Übergeben einer Liste mit ChatParticipant-Objekten, die dem Chatthread hinzugefügt werden sollen. Das ChatParticipant-Objekt wird mit einem CommunicationIdentifier-Objekt initialisiert. Mögliche Typen für CommunicationIdentifier sind CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier und PhoneNumberIdentifier. Wenn Sie beispielsweise ein CommunicationIdentifier-Objekt abrufen möchten, müssen Sie eine Zugriffs-ID übergeben, die Sie gemäß der Anleitung zum Erstellen eines Benutzers erstellt haben.

Das Antwortobjekt der Methode createChatThread enthält die chatThread-Details. Um mit Chatthreadvorgängen wie dem Hinzufügen von Teilnehmern, dem Senden einer Nachricht oder dem Löschen einer Nachricht interagieren zu können, muss eine chatThreadClient-Clientinstanz mithilfe der Methode GetChatThreadClient im ChatClient-Client instanziiert werden.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Abrufen eines Clients für den Chatthread

Die GetChatThreadClient-Methode gibt einen Threadclient für einen bereits vorhandenen Thread zurück. Sie kann zum Durchführen von Vorgängen im erstellten Thread verwendet werden: Hinzufügen von Mitgliedern, Senden einer Nachricht usw. „threadId“ ist die eindeutige ID des vorhandenen Chatthreads.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Auflisten aller Chatthreads

Verwenden Sie GetChatThreads, um alle Chatthreads abzurufen, zu denen der Benutzer gehört.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Senden einer Nachricht an einen Chatthread

Verwenden Sie SendMessage, um eine Nachricht an einen Thread zu senden.

  • Verwenden Sie content, um den Inhalt für die Nachricht anzugeben. Dies ist erforderlich.
  • Verwenden Sie type, um den Inhaltstyp der Nachricht anzugeben (beispielsweise „Text“ oder „Html“). Ohne Angabe wird „Text“ festgelegt.
  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben. Ohne Angabe wird eine leere Zeichenfolge festgelegt.
  • Verwenden Sie optional metadata, um alle zusätzlichen Daten einzubeziehen, die Sie zusammen mit der Nachricht senden möchten. Dieses Feld bietet Entwicklern einen Mechanismus, um die Chatnachrichtenfunktionalität zu erweitern und benutzerdefinierte Informationen für Ihren Anwendungsfall hinzuzufügen. Wenn Sie beispielsweise einen Dateilink in der Nachricht freigeben, sollten Sie „hasAttachment:true“ in den Metadaten hinzufügen, damit die Anwendung des Empfängers diese analysieren und entsprechend anzeigen kann.
SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Empfangen von Chatnachrichten aus einem Chatthread

Sie können Chatnachrichten abrufen, indem Sie die GetMessages-Methode auf dem Chatthreadclient jeweils nach dem angegebenen Intervallzeitraum abfragen.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Für GetMessages wird der optionale Parameter DateTimeOffset verwendet. Bei Angabe dieses Offsetwerts erhalten Sie Nachrichten, die nach diesem Datum empfangen, aktualisiert oder gelöscht wurden. Beachten Sie hierbei Folgendes: Es werden auch Nachrichten zurückgegeben, die vor dem Offsetdatum empfangen, aber erst danach bearbeitet oder entfernt wurden.

GetMessages gibt die aktuelle Version der Nachricht zurück, einschließlich aller Bearbeitungen oder Löschungen, die für die Nachricht mit UpdateMessage und DeleteMessage durchgeführt wurden. Für gelöschte Nachrichten wird von chatMessage.DeletedOn ein datetime-Wert zurückgegeben, mit dem der Löschzeitpunkt der Nachricht angegeben wird. Für bearbeitete Nachrichten gibt chatMessage.EditedOn einen datetime-Wert zurück, mit dem der Bearbeitungszeitpunkt der Nachricht angegeben wird. Auf den ursprünglichen Zeitpunkt der Nachrichtenerstellung kann mit chatMessage.CreatedOn zugegriffen werden. Dieses Element kann zum Sortieren der Nachrichten genutzt werden.

Mit GetMessages werden unterschiedliche Nachrichtentypen zurückgegeben, die mit chatMessage.Type identifiziert werden können. Diese Typen lauten:

  • Text: Reguläre Chatnachricht, die von einem Threadmitglied gesendet wurde.

  • Html: Eine formatierte Textnachricht. Beachten Sie, dass Communication Services-Benutzer derzeit keine RichText-Nachrichten senden können. Dieser Nachrichtentyp wird von Nachrichten unterstützt, die in Teams-Interoperabilitätsszenarien von Teams-Benutzern an Communication Services-Benutzer gesendet werden.

  • TopicUpdated: Systemnachricht, die angibt, dass das Thema aktualisiert wurde (schreibgeschützt)

  • ParticipantAdded: Systemnachricht mit dem Hinweis, dass dem Chatthread mindestens ein Teilnehmer hinzugefügt wurde (schreibgeschützt)

  • ParticipantRemoved: Systemnachricht mit dem Hinweis, dass ein Teilnehmer aus dem Chatthread entfernt wurde

Weitere Details finden Sie unter Nachrichtentypen.

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Nach der Erstellung eines Threads können Sie dafür Benutzer hinzufügen und entfernen. Durch Hinzufügen von Benutzern gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Thread und zum Hinzufügen/Entfernen anderer Teilnehmer. Stellen Sie vor dem Aufrufen von AddParticipants sicher, dass Sie ein neues Zugriffstoken und eine Identität für den Benutzer beschafft haben. Der Benutzer benötigt dieses Zugriffstoken, um den Chatclient initialisieren zu können.

Verwenden Sie AddParticipants, um dem Chatthread einen oder mehrere Teilnehmer hinzuzufügen. Für die einzelnen Threadteilnehmer werden jeweils folgende Attribute unterstützt:

  • communicationUser (erforderlich) ist die Identität des Threadteilnehmers.
  • displayName (optional) ist der Anzeigename für den Threadteilnehmer.
  • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.
var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Abrufen der Threadteilnehmer

Verwenden Sie GetParticipants, um die Teilnehmer des Chatthreads abzurufen.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Senden einer Lesebestätigung

Verwenden Sie SendReadReceipt, um andere Teilnehmer darüber zu informieren, dass die Nachricht vom Benutzer gelesen wurde.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Ausführen des Codes

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

  • Erstellen Sie ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie auf der Seite zum Erstellen eines kostenloses Azure-Kontos.

  • Installieren Sie Xcode und CocoaPods. Sie verwenden Xcode zum Erstellen einer iOS-Anwendung für die Schnellstartanleitung und CocoaPods zum Installieren der Abhängigkeiten.

  • Erstellen Sie eine Azure Communication Services-Ressource. Ausführlichere Informationen finden Sie unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Sie müssen den Endpunkt und die Verbindungszeichenfolge Ihrer Ressource für diese Schnellstartanleitung aufzeichnen.

  • Erstellen Sie zwei Benutzer in Azure Communication Services und stellen Sie ein Benutzerzugriffstoken für diese Benutzer aus. Legen Sie den Bereich auf Chat fest und notieren Sie sich die Tokenzeichenfolge und die userId-Zeichenfolge. In dieser Schnellstartanleitung erstellen Sie einen Thread mit einem ersten Teilnehmer und fügen anschließend einen zweiten Teilnehmer hinzu. Sie können auch die Azure CLI verwenden und den folgenden Befehl mit Ihrer Verbindungszeichenfolge ausführen, um einen Benutzer und ein Zugriffstoken zu erstellen.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Ausführliche Informationen finden Sie unter Verwenden der Azure CLI zum Erstellen und Verwalten von Zugriffstoken.

Einrichten

Erstellen einer neuen iOS-Anwendung

Starten Sie Xcode, und wählen Sie Create a new Xcode project (Neues Xcode-Projekt erstellen) aus. Wählen Sie anschließend iOS als Plattform und App für die Vorlage aus.

Geben Sie ChatQuickstart als Projektnamen ein. Wählen Sie anschließend Storyboard als Schnittstelle, UIKit App Delegate als Lebenszyklus und Swift als Sprache aus.

Wählen Sie die Option Weiter und dann das Verzeichnis aus, in dem Sie das Projekt erstellen möchten.

Installieren der Bibliotheken

Verwenden Sie CocoaPods, um die erforderlichen Communication Services-Abhängigkeiten zu installieren.

Navigieren Sie in der Befehlszeile zum Stammverzeichnis des iOS-Projekts ChatQuickstart. Erstellen Sie mit dem folgenden Befehl eine Podfile-Datei: pod init.

Öffnen Sie die Podfile-Datei, und fügen Sie dem Ziel ChatQuickstart die folgenden Abhängigkeiten hinzu:

pod 'AzureCommunicationChat', '~> 1.3.6'

Installieren Sie die Abhängigkeiten mit dem folgenden Befehl: pod install. Beachten Sie, dass hierbei auch ein Xcode-Arbeitsbereich erstellt wird.

Öffnen Sie das Projekt nach dem Ausführen von pod install erneut in Xcode, indem Sie den neu erstellten Arbeitsbereich .xcworkspace auswählen.

Einrichten der Platzhalter

Öffnen Sie den Arbeitsbereich ChatQuickstart.xcworkspace in Xcode und anschließend ViewController.swift.

In dieser Schnellstartanleitung fügen Sie Ihren Code dem viewController-Element hinzu und sehen sich die Ausgabe in der Xcode-Konsole an. Das Erstellen einer Benutzeroberfläche unter iOS wird in dieser Schnellstartanleitung nicht beschrieben.

Importieren Sie im oberen Bereich von viewController.swift die Bibliotheken AzureCommunication und AzureCommunicationChat:

import AzureCommunicationCommon
import AzureCommunicationChat

Kopieren Sie den folgenden Code in die Methode viewDidLoad() von ViewController:

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

Zu Demonstrationszwecken wird Ihr Code mithilfe eines Semaphors synchronisiert. In den folgenden Schritten ersetzen Sie die Platzhalter durch Beispielcode, indem Sie die Chatbibliothek von Azure Communication Services verwenden.

Erstellen eines Chatclients

Zum Erstellen eines Chatclients verwenden Sie Ihren Communication Services-Endpunkt und das Zugriffstoken, das im Rahmen der erforderlichen Schritte zur Vorbereitung generiert wurde.

Informieren Sie sich über Benutzerzugriffstoken.

Die Erstellung einer Dienstebene zum Verwalten von Token für Ihre Chatanwendung wird empfohlen, wird aber in diesem Schnellstart nicht behandelt. Weitere Informationen zur Chatarchitektur finden Sie hier.

Ersetzen Sie den Kommentar <CREATE A CHAT CLIENT> durch den folgenden Codeausschnitt:

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

Ersetzen Sie <ACS_RESOURCE_ENDPOINT> durch den Endpunkt Ihrer Azure Communication Services-Ressource. Ersetzen Sie <ACCESS_TOKEN> durch ein gültiges Communication Services-Zugriffstoken.

Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features des Chat SDK von Azure Communication Services für iOS verwendet.

Name BESCHREIBUNG
ChatClient Diese Klasse wird für die Chatfunktionalität benötigt. Sie instanziieren sie mit Ihren Abonnementinformationen und verwenden sie zum Erstellen, Abrufen und Löschen von Threads sowie zum Abonnieren von Chatereignissen.
ChatThreadClient Diese Klasse wird für die Chatthreadfunktionalität benötigt. Sie erhalten über ChatClient eine Instanz und verwenden sie zum Senden, Empfangen, Aktualisieren und Löschen von Nachrichten. Darüber hinaus können Sie sie auch verwenden, um Benutzer hinzuzufügen, zu entfernen und abzurufen sowie Eingabebenachrichtigungen und Lesebestätigungen zu senden.

Starten eines Chatthreads

CreateChatThreadResult ist die Antwort, die beim Erstellen eines Chatthreads zurückgegeben wird. Sie enthält die chatThread-Eigenschaft, bei der es sich um das ChatThreadProperties-Objekt handelt. Dieses Objekt enthält die threadId, mit der ein ChatThreadClient zum Ausführen von Vorgängen für den erstellten Thread (Teilnehmende hinzufügen, Nachricht senden usw.) abgerufen werden kann.

Ersetzen Sie den Kommentar <CREATE A CHAT THREAD> durch den folgenden Codeausschnitt:

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

Ersetzen Sie <USER_ID> durch eine gültige Communication Services-Benutzer-ID.

Sie verwenden hier einen Semaphor, um auf den Fertigstellungshandler zu warten, bevor der Vorgang fortgesetzt wird. Die Thread-ID (threadId) aus der Antwort an den Fertigstellungshandler verwenden Sie in späteren Schritten.

Auflisten aller Chatthreads

Nach dem Erstellen eines Chatthreads können wir alle Chatthreads auflisten, indem wir für ChatClient die listChatThreads-Methode aufrufen. Ersetzen Sie den Kommentar <LIST ALL CHAT THREADS> durch folgenden Code:

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

Abrufen eines Clients für den Chatthread

Die createClient-Methode gibt einen ChatThreadClient für einen bereits vorhandenen Thread zurück. Er kann verwendet werden, um Vorgänge wie das Hinzufügen von Teilnehmern oder das Senden einer Nachricht im erstellten Thread auszuführen. „threadId“ ist die eindeutige ID des vorhandenen Chatthreads.

Ersetzen Sie den Kommentar <GET A CHAT THREAD CLIENT> durch folgenden Code:

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

Senden einer Nachricht an einen Chatthread

Verwenden Sie die send-Methode, um eine Nachricht an einen Thread zu senden, der durch die threadId identifiziert wird.

SendChatMessageRequest wird verwendet, um die Nachrichtenanforderung zu beschreiben:

  • Verwenden Sie content, um den Inhalt der Chatnachricht anzugeben.
  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben.
  • Verwenden Sie type, um den Nachrichtentyp anzugeben, etwa Text oder HTML.
  • Verwenden Sie optional metadata, um alle zusätzlichen Daten einzubeziehen, die Sie zusammen mit der Nachricht senden möchten. Dieses Feld bietet Entwicklern einen Mechanismus, um die Chatnachrichtenfunktionalität zu erweitern und benutzerdefinierte Informationen für Ihren Anwendungsfall hinzuzufügen. Wenn Sie beispielsweise einen Dateilink in der Nachricht freigeben, sollten Sie „hasAttachment:true“ in den Metadaten hinzufügen, damit die Anwendung des Empfängers diese analysieren und entsprechend anzeigen kann.

SendChatMessageResult ist die Antwort, die nach dem Senden einer Nachricht zurückgegeben wird. Sie enthält eine ID, bei der es sich um die eindeutige ID der Nachricht handelt.

Ersetzen Sie den Kommentar <SEND A MESSAGE> durch den folgenden Codeausschnitt:

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

Senden einer Lesebestätigung

Die Methode sendReadReceipt kann verwendet werden, um im Auftrag eines Benutzers ein Lesebestätigungsereignis in einem Thread zu veröffentlichen. messageId ist die eindeutige ID der Chatnachricht, die gelesen wurde.

Ersetzen Sie den Kommentar <SEND A READ RECEIPT> durch den folgenden Code:

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

Empfangen von Chatnachrichten aus einem Chatthread

Bei der Echtzeitsignalisierung können Sie eine Funktion abonnieren, mit der auf neue eingehende Nachrichten gelauscht wird und die aktuellen Nachrichten im Arbeitsspeicher entsprechend aktualisiert werden. Azure Communication Services unterstützt eine Liste mit Ereignissen, die Sie abonnieren können.

Ersetzen Sie den Kommentar <RECEIVE MESSAGES> durch den folgenden Code. Versuchen Sie nach dem Aktivieren von Benachrichtigungen, neue Nachrichten zu senden, um ChatMessageReceivedEvents anzuzeigen.

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

Alternativ können Sie Chatnachrichten auch abrufen, indem Sie die listMessages-Methode jeweils nach dem angegebenen Intervallzeitraum abfragen. Sehen Sie sich den folgenden Codeausschnitt für listMessages an.

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

Hinzufügen eines Benutzers als Teilnehmer des Chatthreads

Nach der Erstellung eines Threads können Sie dafür Benutzer hinzufügen und entfernen. Durch Hinzufügen von Benutzern gewähren Sie ihnen Zugriff zum Senden von Nachrichten an den Thread und zum Hinzufügen/Entfernen anderer Teilnehmer. Stellen Sie vor dem Aufrufen von add sicher, dass Sie ein neues Zugriffstoken und eine Identität für den Benutzer beschafft haben. Der Benutzer benötigt dieses Zugriffstoken, um den Chatclient initialisieren zu können.

Verwenden Sie die add-Methode von ChatThreadClient, um dem Chatthread einzelne oder mehrere Teilnehmende hinzuzufügen. Für die einzelnen Threadteilnehmer werden jeweils folgende Attribute unterstützt:

  • id (erforderlich) ist die Identität des Threadteilnehmers.
  • displayName (optional) ist der Anzeigename für den Threadteilnehmer.
  • shareHistoryTime (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.

Ersetzen Sie den Kommentar <ADD A USER> durch folgenden Code:

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

Ersetzen Sie <USER_ID> durch die Communication Services-Benutzer-ID des Benutzers, der hinzugefügt werden soll.

Auflisten der Benutzer in einem Thread

Verwenden Sie die listParticipants-Methode, um alle Teilnehmenden eines bestimmten Chatthreads abzurufen.

Ersetzen Sie den <LIST USERS>-Kommentar durch folgenden Code:

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

Pushbenachrichtigungen

Mit Pushbenachrichtigungen werden Clients über in einem Chatthread eingehende Nachrichten in Situationen benachrichtigt, in denen die mobile App nicht im Vordergrund ausgeführt wird. Derzeit wird das Senden von Chatpushbenachrichtigungen über den Notification Hub nur für das iOS SDK in Version 1.3.0 unterstützt. Weitere Informationen finden Sie im Artikel Aktivieren von Pushbenachrichtigungen in Ihrer Chat-App.

Ausführen des Codes

Klicken Sie in Xcode auf die Ausführungsschaltfläche, um das Projekt zu erstellen und auszuführen. In der Konsole können Sie sich die Ausgabe des Codes sowie die Protokollierungsausgabe des Chatclients ansehen.

Hinweis: Legen Sie Build Settings > Build Options > Enable Bitcode auf No fest. Derzeit unterstützt das AzureCommunicationChat SDK für iOS die Aktivierung von Bitcode nicht. Im folgenden GitHub-Problem wird dies nachverfolgt.

Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Benutzer erstellen

Führen Sie diese Schritte in Power Automate durch, während Ihr Power Automate-Flow im Bearbeitungsmodus geöffnet ist.

So fügen Sie ihrem Workflow mithilfe des Communication Services Identity-Connectors einen neuen Schritt hinzu:

  1. Wählen Sie im Designer unter dem Schritt, in dem Sie die neue Aktion hinzufügen möchten, die Option Neuer Schritt aus. Alternativ können Sie die neue Aktion zwischen den Schritten hinzufügen, indem Sie den Mauszeiger über den Pfeil zwischen diesen Schritten bewegen, das Pluszeichen (+) und dann die Option Aktion hinzufügen auswählen.

  2. Geben Sie im Suchfeld Vorgang auswählen den Suchbegriff Communication Services Identity ein. Wählen Sie in der Aktionsliste die Aktion Benutzer erstellen aus.

    Screenshot des Azure Communication Services Identity-Connectors mit der Aktion „Benutzer erstellen“.

  3. Geben Sie die Verbindungszeichenfolge ein. Um die Verbindungszeichenfolgen-URL im Azure-Portal abzurufen, wechseln Sie zur Ressource „Azure Communication Services“. Wählen Sie im Ressourcenmenü Schlüssel und dann Verbindungszeichenfolge aus. Klicken Sie auf das Symbol „Kopieren“, um die Verbindungszeichenfolge zu kopieren.

    Screenshot: Bereich „Schlüssel“ für eine Azure Communication Services-Ressource

  4. Geben Sie einen Namen für die Verbindung ein.

  5. Wählen Sie Erweiterte Optionen anzeigen und dann den Tokenbereich aus. Dadurch wird ein Zugriffstoken und dessen Ablaufzeit mit dem angegebenen Bereich generiert. Diese Aktion generiert auch eine Benutzer-ID, bei der es sich um eine Communication Services-Benutzeridentität handelt.

    Screenshot der Optionen „Create user action“ (Benutzeraktion erstellen) des Azure Communication Services Identity-Connectors.

  6. Wählen Sie unter Tokenbereichselement die Option Chat aus.

    Screenshot der erweiterten Optionen des Azure Communication Services Chat-Connectors.

  7. Klicken Sie auf Erstellen. Die Benutzer-ID und ein Zugriffstoken werden angezeigt.

Erstellen eines Chatthreads

  1. Fügen Sie eine neue Aktion hinzu.

  2. Geben Sie im Suchfeld Vorgang auswählen den Suchbegriff Communication Services Chat ein. Wählen Sie in der Aktionsliste die Aktion Chat-Thread erstellen aus.

    Screenshot des Azure Communication Services Chat-Connectors mit der Aktion „Chatthread erstellen“.

  3. Geben Sie die Endpunkt-URL für Azure Communication Services an. Um die Endpunkt-URL im Azure-Portal abzurufen, wechseln Sie zur Ressource „Azure Communication Services“. Wählen Sie im Ressourcenmenü Schlüssel und dann Endpunkt aus.

  4. Geben Sie einen Namen für die Verbindung ein.

  5. Wählen Sie das Zugriffstoken aus, das im vorherigen Abschnitt generiert wurde, und fügen Sie dann eine Beschreibung des Themas des Chat-Threads hinzu. Fügen Sie den erstellten Benutzer hinzu, und geben Sie einen Namen für den Teilnehmer ein.

    Screenshot: Aktionsdialogfeld „Chat-Thread erstellen“ des Chat-Connectors von Azure Communication Services

Senden einer Nachricht

  1. Fügen Sie eine neue Aktion hinzu.

  2. Geben Sie im Suchfeld Vorgang auswählen den Suchbegriff Communication Services Chat ein. Wählen Sie in der Aktionsliste die Aktion Nachricht an Chat-Thread senden aus.

    Screenshot des Azure Communication Services Chat-Connectors mit der Aktion „Chatnachricht senden“.

  3. Geben Sie das Zugriffstoken, die Thread-ID, den Inhalt und den Namen ein.

    Screenshot: Aktionsdialogfeld „Nachricht an Chat-Thread senden“ des Chat-Connectors von Azure Communication Services

Auflisten von Chatthreadnachrichten

So überprüfen Sie, ob Sie eine Nachricht ordnungsgemäß gesendet haben:

  1. Fügen Sie eine neue Aktion hinzu.

  2. Geben Sie im Suchfeld Vorgang auswählen den Suchbegriff Communication Services Chat ein. Wählen Sie in der Aktionsliste die Aktion Chat-Thread-Nachrichten auflisten aus.

    Screenshot des Azure Communication Services Chat-Connectors mit der Aktion „Chatnachrichten auflisten“.

  3. Geben Sie das Zugriffstoken und die Thread-ID ein.

    Screenshot: Aktionsdialogfeld „Chat-Thread-Nachrichten auflisten“ des Chat-Connectors von Azure Communication Services

Testen Ihrer Logik-App

Wählen Sie auf der Symbolleiste des Designers die Option Ausführen aus, um Ihren Workflow manuell zu starten. Der Workflow erstellt einen Benutzer, gibt ein Zugriffstoken für diesen Benutzer aus, entfernt dann das Token und löscht den Benutzer. Weitere Informationen finden Sie im Abschnitt zum Ausführen Ihres Workflows.

Wählen Sie jetzt Chat-Thread-Nachrichten auflisten aus. Schauen Sie in den Aktionsausgaben nach, ob die Nachricht gesendet wurde.

Screenshot: Aktionsergebnisse zu „Chat-Nachrichten senden“ des Chat-Connectors von Azure Communication Services

Bereinigen von Workflow-Ressourcen

Zur Bereinigung Ihres Logik-Apps-Workflows und von verwandten Ressourcen finden Sie weitere Informationen unter Bereinigen von Logic Apps-Ressourcen.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie Folgendes gelernt:

  • Erstellen eines Chatclients
  • Erstellen eines Threads mit zwei Benutzern
  • Senden einer Nachricht an den Thread
  • Empfangen von Nachrichten aus einem Thread
  • Entfernen von Benutzern aus einem Thread

Ausprobieren der Hero-App für Chats

Das könnte Sie auch interessieren: