Freigeben über

Azure Communication Chat-Clientbibliothek für Java– Version 1.3.13

  • Artikel

Azure Communication Chat enthält die APIs, die in Chatanwendungen für Azure Communication Services verwendet werden.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek annehmen möchten, die nicht in der BoM vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version>1.3.13</version>
</dependency>

Wichtige Begriffe

Eine Chatunterhaltung wird durch einen Chatthread dargestellt. Jeder Benutzer im Chatthread wird als Teilnehmer bezeichnet. Teilnehmer können privat in einem 1:1-Chat miteinander chatten oder sich in einem 1:N-Gruppenchat zusammenraufen.

Nachdem Sie eine ChatClient - und eine ChatThreadClient -Klasse initialisiert haben, können Sie die folgenden Chatvorgänge ausführen:

Erstellen, Abrufen, Auflisten, Aktualisieren und Löschen von Chatthreads

Senden, Abrufen, Auflisten, Aktualisieren und Löschen von Chatnachrichten

Abrufen, Hinzufügen und Entfernen von Teilnehmern

Senden und Abrufen von Lesebestätigungen

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Festlegen des Azure Communication Resource-Endpunkts nach der Erstellung

endpoint = "https:// Azure-Communication-Resource-Name.communications.azure.com"

Anfordern eines Benutzerzugriffstokens

Mit Benutzerzugriffstoken können Sie Clientanwendungen erstellen, die gegenüber Azure Communication Services direkt authentifiziert werden. Sie generieren diese Token auf Ihrem Server, übergeben sie an ein Clientgerät zurück und verwenden sie dann, um die Communication Services-SDKs zu initialisieren.

Erfahren Sie, wie Sie Benutzerzugriffstoken aus Benutzerzugriffstoken generieren.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten Aufgaben abdecken, einschließlich:

Erstellen des Chatclients

String endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com";

// Your user access token retrieved from your trusted service
String token = "SECRET";
CommunicationTokenCredential credential = new CommunicationTokenCredential(token);

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

Chatthreadvorgänge

Erstellen eines Chatthreads

Zum Erstellen eines Chatclients verwenden Sie den Communications Service-Endpunkt und das Zugriffstoken, das im Rahmen der erforderlichen Schritte 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.

Verwenden Sie die createChatThread-Methode, um einen Chatthread zu erstellen. createChatThreadOptions wird verwendet, um die Threadanforderung zu beschreiben. Im folgenden Codeausschnitt wird ein Beispiel gezeigt.

  • Verwenden Sie topic , um ein Threadthema zu geben.
  • Verwenden Sie participants , um die Threadteilnehmer aufzulisten, die dem Thread hinzugefügt werden sollen.

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

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Participant Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .setParticipants(participants);
CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);

String chatThreadId = result.getChatThread().getId();

Abrufen der Eigenschaften eines Chatthreads

Die getChatThreadProperties -Methode ruft die Eigenschaften eines Threads aus dem Dienst ab.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient("Id");
ChatThreadProperties chatThreadProperties = chatThreadClient.getProperties();

Löschen eines Threads

Die Verwendung deleteChatThread der Methode zum Löschen eines Chatthreads chatThreadId ist die eindeutige ID des Chatthreads.

String chatThreadId = "Id";
chatClient.deleteChatThread(chatThreadId);

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.

String chatThreadId = "Id";
ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Aktualisieren eines Chatthreadthemas

Verwenden Sie die - updateTopic Methode, um das Thema topic eines Threads zu aktualisieren, um das neue Thema des Threads zu enthalten.

chatThreadClient.updateTopic("New Topic");

Chatnachrichtenvorgänge

Senden einer Chatnachricht

Verwenden Sie die sendMessage -Methode, um eine Chatnachricht an den Chatthread zu senden, mit dem erstellt chatThreadClient wurde. sendChatMessageOptions wird verwendet, um die Chatnachrichtenanforderung zu beschreiben, ein Beispiel ist im folgenden Codeausschnitt dargestellt.

  • Verwenden Sie content, um den Inhalt der Chatnachricht anzugeben.
  • Verwenden Sie priority , um die Prioritätsstufe für Chatnachrichten anzugeben, z. B. "Normal" oder "Hoch".
  • Verwenden Sie senderDisplayName, um den Anzeigenamen des Absenders anzugeben.

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

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Message content")
    .setSenderDisplayName("Sender Display Name");

SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

Abrufen einer Chatnachricht

Die getMessage -Methode ruft eine Chatnachricht vom Dienst ab. chatMessageId ist die eindeutige ID der Chatnachricht.

String chatMessageId = "Id";
ChatMessage chatMessage = chatThreadClient.getMessage(chatMessageId);

Abrufen von Chatnachrichten

Sie können Chatnachrichten mit der listMessages -Methode auf dem Chatthreadclient in bestimmten Intervallen (Abruf) abrufen.

PagedIterable<ChatMessage> chatMessagesResponse = chatThreadClient.listMessages();
chatMessagesResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(message ->
        System.out.printf("Message id is %s.", 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.

listMessages gibt verschiedene Arten von Nachrichten zurück, die durch chatMessage.getType()identifiziert werden können. Diese Typen lauten:

  • text: Reguläre Chatnachricht, die von einem Threadteilnehmer gesendet wurde

  • html: HTML-Chatnachricht, die von einem Threadteilnehmer gesendet wurde

  • topicUpdated: Systemnachricht, die angibt, dass das Thema aktualisiert wurde

  • participantAdded: Systemnachricht mit dem Hinweis, dass dem Chatthread mindestens ein Teilnehmer hinzugefügt wurde

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

Weitere Details finden Sie unter Nachrichtentypen.

Aktualisieren einer Chatnachricht

Verwenden Sie updateMessage , um eine Chatnachricht zu aktualisieren, die durch chatThreadId und messageId identifiziert wird. chatMessageId ist die eindeutige ID der Chatnachricht. updateChatMessageOptions wird verwendet, um die Anforderung eines Chatnachrichtenupdates zu beschreiben, ein Beispiel ist im folgenden Codeausschnitt dargestellt.

  • Verwenden Sie content , um einen neuen Chatnachrichteninhalt bereitzustellen.
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

Löschen einer Chatnachricht

Verwenden Sie updateMessage , um eine chatMessageId identifizierte Chatnachricht zu aktualisieren. chatMessageId ist die eindeutige ID der Chatnachricht.

String chatMessageId = "Id";
chatThreadClient.deleteMessage(chatMessageId);

Chatthread-Teilnehmervorgänge

Auflisten von Chatteilnehmern

Verwenden Sie listParticipants , um eine ausgelagerte Sammlung abzurufen, die die Teilnehmer des Chatthreads enthält.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(chatParticipant ->
        System.out.printf("Participant id is %s.", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId()));
});

Hinzufügen von Teilnehmern

Verwenden Sie addParticipants die -Methode, um Dem Chatthread Teilnehmer hinzuzufügen. participants Liste der Teilnehmer, die dem Thread hinzugefügt werden sollen;

  • communicationIdentifier, erforderlich, ist der CommunicationIdentifier, den Sie mithilfe von CommunicationIdentityClient erstellt haben. Weitere Informationen finden Sie unter Erstellen eines Benutzers.
  • display_name (optional) ist der Anzeigename für das Threadmitglied.
  • share_history_time (optional) ist der Zeitpunkt, ab dem der Chatverlauf für das Mitglied 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. Geben Sie das aktuelle Datum an, um den Verlauf vor dem Hinzufügezeitpunkt des Mitglieds nicht freizugeben. Geben Sie ein gewünschtes Datum an, um nur einen Teil des Verlaufs freizugeben.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

chatThreadClient.addParticipants(participants);

Entfernen eines Teilnehmers

Verwenden Sie removeParticipant die -Methode, um einen Teilnehmer aus dem Chatthread zu entfernen. identifier ist der CommunicationIdentifier, den Sie erstellt haben.

chatThreadClient.removeParticipant(user);

Lesebestätigungsvorgänge

Senden einer Lesebestätigung

Verwenden Sie sendReadReceipt die -Methode, um im Namen eines Benutzers ein Lesebestätigungsereignis in einem Chatthread zu posten. chatMessageId ist die eindeutige ID der Chatnachricht, die gelesen wurde.

String chatMessageId = "Id";
chatThreadClient.sendReadReceipt(chatMessageId);

Abrufen von Lesebestätigungen

getReadReceipts -Methode ruft Lesebestätigungen für einen Chatthread ab.

PagedIterable<ChatMessageReadReceipt> readReceiptsResponse = chatThreadClient.listReadReceipts();
readReceiptsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(readReceipt ->
        System.out.printf("Read message id is %s.", readReceipt.getChatMessageId()));
});

Eingabe von Benachrichtigungsvorgängen

Senden einer Eingabebenachrichtigung

Verwenden Sie sendTypingNotification die -Methode, um ein Eingabebenachrichtigungsereignis im Namen eines Benutzers in einem Chatthread zu posten. typingNotificationOptions wird verwendet, um die Eingabebenachrichtigungsanforderung zu beschreiben.

  • Verwenden Sie senderDisplayName , um den Anzeigenamen des Benachrichtigungssenders festzulegen.
TypingNotificationOptions options = new TypingNotificationOptions();
options.setSenderDisplayName("Sender Display Name");
chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

Problembehandlung

Läuft.

Nächste Schritte

Sehen Sie sich andere Clientbibliotheken für den Azure-Kommunikationsdienst an.