Dela via

Snabbstart: Lägga till chatt i din app

  • Artikel

Kom igång med Azure Communication Services med hjälp av Communication Services Chat SDK för att lägga till realtidschatt i ditt program. I den här snabbstarten använder vi Chat SDK för att skapa chatttrådar som gör att användare kan ha konversationer med varandra. Mer information om chattbegrepp finns i den konceptuella chattdokumentationen.

Förutsättningar

  • Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.

  • En aktiv Communication Services-resurs och anslutningssträng. Skapa en Communication Services-resurs.

  • Installera Azure CLI.

  • Observera resursslutpunkten för Communication Services. Du kan hämta slutpunkten från Azure-portalen. Du kan också hitta slutpunkts-URL:en i anslutningssträng. Det är url:en som kommer efter endpoint= och börjar med https://.

  • En användaråtkomsttoken. Se till att ange omfånget till chatt och notera tokensträngen samt user_id strängen. Du kan också använda Azure CLI och köra kommandot nedan med din anslutningssträng för att skapa en användare och en åtkomsttoken.

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

    Mer information finns i Använda Azure CLI för att skapa och hantera åtkomsttoken.

Konfigurera

Lägga till tillägget

Lägg till Azure Communication Services-tillägget för Azure CLI med hjälp az extension av kommandot .

az extension add --name communication

Logga in på Azure CLI

Du måste logga in på Azure CLI. Du kan logga in med az login kommandot från terminalen och ange dina autentiseringsuppgifter.

(Valfritt) Använda Azure CLI-identitetsåtgärder utan att skicka in en slutpunkt eller åtkomsttoken

Lagra slutpunkten i en miljövariabel

Du kan konfigurera AZURE_COMMUNICATION_ENDPOINT miljövariabeln så att den använder Azure CLI-chattåtgärder utan att behöva använda --endpoint för att skicka in slutpunkten. Om du vill konfigurera en miljövariabel öppnar du ett konsolfönster och väljer ditt operativsystem på flikarna nedan. Ersätt <yourEndpoint> med din faktiska slutpunkt.

Öppna ett konsolfönster och ange följande kommando:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

När du har lagt till miljövariabeln kan du behöva starta om alla program som körs och som behöver läsa in miljövariabeln, däribland konsolfönstret. Om du till exempel använder Visual Studio som redigerare startar du om Visual Studio innan du kör exemplet.

Lagra din åtkomsttoken i en miljövariabel

Du kan konfigurera AZURE_COMMUNICATION_ACCESS_TOKEN miljövariabeln så att den använder Azure CLI-chattåtgärder utan att behöva använda --access-token för att skicka in åtkomsttoken. Om du vill konfigurera en miljövariabel öppnar du ett konsolfönster och väljer ditt operativsystem på flikarna nedan. Ersätt <yourAccessToken> med din faktiska åtkomsttoken.

Öppna ett konsolfönster och ange följande kommando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

När du har lagt till miljövariabeln kan du behöva starta om alla program som körs och som behöver läsa in miljövariabeln, däribland konsolfönstret. Om du till exempel använder Visual Studio som redigerare startar du om Visual Studio innan du kör exemplet.

Operations

Starta en chatttråd

thread create Använd kommandot för att skapa en chatttråd.

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

Om du har lagrat slutpunkten och åtkomsttoken i miljövariabler enligt ovan behöver du inte skicka dem till kommandot.

az communication chat thread create --topic "<chatTopic>"
  • Använd <chatTopic> för att ge tråden ett ämne. Du kan uppdatera ämnet när chatttråden har skapats med hjälp thread update-topic av kommandot .
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Uppdatera ämnet för en chatttråd

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Ersätt <chatTopic> med det nya chattavsnittet som du vill ange.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Visa en lista över alla chatttrådar

Kommandot thread list returnerar listan över chatttrådar för en användare.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Du <startTime> kan också ange den tidigaste tidpunkten för att hämta chattmeddelanden.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Skicka ett meddelande till en chatttråd

message send Använd kommandot för att skicka ett meddelande till en chatttråd som du har skapat, identifierad av threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Använd <content> för att ange innehållet i chattmeddelandet.
  • Använd <messageType> för att ange meddelandeinnehållstypen. Möjliga värden är text och html. Om du inte anger något värde är textstandardvärdet .
  • Om <displayName> du vill kan du ange avsändarens visningsnamn.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Visa en lista över chattmeddelanden i en chatttråd

Kommandot message list returnerar listan över chattmeddelanden i en chatttråd.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Du <startTime> kan också ange den tidigaste tidpunkten för att hämta chattmeddelanden.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Ta emot ett chattmeddelande från en chatttråd

Du kan hämta chattmeddelanden med hjälp message list av kommandot .

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Ersätt <messageId> med ID:t för det meddelande som du vill hämta.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Skicka läskvitto

Du använder message receipt send kommandot för att publicera en läskvittohändelse i en tråd för en användares räkning.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Ersätt <messageId> för att ange ID för det senaste meddelandet som lästs av den aktuella användaren.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Lägga till en användare som deltagare i chatttråden

När du skapar en chatttråd kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst för att kunna skicka meddelanden till chatttråden och lägga till eller ta bort andra deltagare. Innan du anropar participant add kommandot kontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Ersätt <userId> med ditt userId.
  • Om <displayName> du vill kan du ange avsändarens visningsnamn.
  • Du <startTime> kan också ange den tidigaste tidpunkten för att hämta chattmeddelanden.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Lista tråddeltagare i en chatttråd

På samma sätt som när du lägger till en deltagare kan du även lista deltagare från en tråd.

Använd participant list kommandot för att hämta deltagarna i tråden.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Om <skip> du vill kan du hoppa över deltagare upp till en angiven position i svaret.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Ta bort en deltagare från en chatttråd

Du kan ta bort en chattdeltagare från en chatttråd med hjälp av kommandot "ta bort deltagare".

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Ersätt <chatThreadId> med ditt chatttråds-ID.
  • Ersätt <userId> med det userId som du vill ta bort från chatttråden.
  • Ersätt <endpoint> med slutpunkten för Azure Communication Services.
  • Ersätt <token> med din åtkomsttoken som hämtades tidigare med kommandot running identity token issue .

Förutsättningar

Innan du kommer igång måste du:

  • Skapa ett Azure-konto med en aktiv prenumeration. Mer information finns i Skapa ett konto kostnadsfritt.

  • Installera Node.js Active LTS- och Maintenance LTS-versioner.

  • Skapa en Azure Communication Services-resurs. Mer information finns i Skapa en Azure Communication Services-resurs. Du måste registrera resursslutpunkten och anslutningssträng för den här snabbstarten.

  • Skapa tre Azure Communication Services-användare och ge dem en användaråtkomsttoken. Se till att ange omfånget till chatt och notera tokensträngen samt user_id strängen. Den fullständiga demonstrationen skapar en tråd med två inledande deltagare och lägger sedan till en tredje deltagare i tråden. Du kan också använda Azure CLI och köra kommandot nedan med din anslutningssträng för att skapa en användare och en åtkomsttoken.

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

    Mer information finns i Använda Azure CLI för att skapa och hantera åtkomsttoken.

Konfigurera

Skapa ett nytt webbprogram

Öppna först terminalen eller kommandofönstret och skapa en ny katalog för din app och navigera till den.

mkdir chat-quickstart && cd chat-quickstart

Kör npm init -y för att skapa en package.json-fil med standardinställningar.

npm init -y

Installera paketen

npm install Använd kommandot för att installera nedanstående Communication Services-SDK:er för JavaScript.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

Alternativet --save visar biblioteket som ett beroende i filen package.json .

Konfigurera appramverket

Den här snabbstarten använder paket för att paketa programtillgångarna. Kör följande kommando för att installera det och lista det som ett utvecklingsberoende i package.json:

npm install parcel --save-dev

Skapa en index.html-fil i projektets rotkatalog. Vi använder den här filen som en mall för att lägga till chattfunktioner med hjälp av Azure Communication Chat SDK för JavaScript.

<!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>

Skapa en fil i rotkatalogen för projektet med namnet client.js för att innehålla programlogik för den här snabbstarten.

Skapa en chattklient

Om du vill skapa en chattklient i webbappen använder du slutpunkten för kommunikationstjänsten och åtkomsttoken som genererades som en del av nödvändiga steg.

Med användaråtkomsttoken kan du skapa klientprogram som autentiserar direkt till Azure Communication Services. Den här snabbstarten beskriver inte hur du skapar en tjänstnivå för att hantera token för chattprogrammet. Mer information om åtkomsttoken finns i chattkoncept för mer information om chattarkitektur och användaråtkomsttoken .

I client.js använder du slutpunkten och åtkomsttoken i koden nedan för att lägga till chattfunktioner med hjälp av Azure Communication Chat SDK för JavaScript.


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!');

Kör koden

Kör följande kommando för att köra programmet:

npx parcel index.html

Öppna webbläsaren och navigera till http://localhost:1234/. I utvecklarverktygskonsolen i webbläsaren bör du se följande:

Azure Communication Chat client created!

Objektmodell

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för JavaScript.

Namn Beskrivning
ChatClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta, ta bort trådar och prenumerera på chatthändelser.
ChatThreadClient Den här klassen behövs för chatttrådsfunktionen. Du hämtar en instans via ChatClient och använder den för att skicka/ta emot/uppdatera/ta bort meddelanden, lägga till/ta bort/hämta användare, skicka skrivmeddelanden och läsa kvitton.

Starta en chatttråd

createThread Använd metoden för att skapa en chatttråd.

createThreadRequest används för att beskriva trådbegäran:

  • Använd topic för att ge ett ämne till den här chatten. Ämnen kan uppdateras när chatttråden har skapats med hjälp av UpdateThread funktionen .
  • Använd participants för att lista de deltagare som ska läggas till i chatttråden.

När den har lösts createChatThread returnerar metoden en CreateChatThreadResult. Den här modellen innehåller en chatThread egenskap där du kan komma åt den id nyligen skapade tråden. Du kan sedan använda id för att hämta en instans av en ChatThreadClient. ChatThreadClient Kan sedan användas för att utföra åtgärden i tråden, till exempel att skicka meddelanden eller visa deltagare.

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>
  });

När du uppdaterar webbläsarfliken bör du se följande i konsolen:

Thread created: <thread_id>

Hämta en chatttrådsklient

Metoden getChatThreadClient returnerar en chatThreadClient för en tråd som redan finns. Den kan användas för att utföra åtgärder i den skapade tråden: lägga till deltagare, skicka meddelande osv. threadId är det unika ID:t för den befintliga chatttråden.

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

Lägg till den här koden i stället för kommentaren <CREATE CHAT THREAD CLIENT> i client.js, uppdatera webbläsarfliken och kontrollera konsolen. Du bör se:

Chat Thread client for threadId: <threadId>

Visa en lista över alla chatttrådar

Metoden listChatThreads returnerar en PagedAsyncIterableIterator av typen ChatThreadItem. Den kan användas för att visa alla chatttrådar. En iterator för [ChatThreadItem] är svaret som returneras från listtrådar

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

Skicka ett meddelande till en chatttråd

Använd sendMessage metoden för att skicka ett meddelande till en tråd som identifieras av threadId.

sendMessageRequest används för att beskriva meddelandebegäran:

  • Använd content för att ange innehållet i chattmeddelandet.

sendMessageOptions används för att beskriva åtgärden valfria params:

  • Använd senderDisplayName för att ange avsändarens visningsnamn.
  • Använd type för att ange meddelandetypen, till exempel "text" eller "html";
  • Om metadata du vill kan du inkludera andra data som du vill skicka tillsammans med meddelandet. Det här fältet innehåller en mekanism för utvecklare att utöka chattmeddelandefunktionerna och lägga till anpassad information för ditt användningsfall. När du till exempel delar en fillänk i meddelandet kanske du vill lägga till "hasAttachment: true" i metadata så att mottagarens program kan parsa det och visa därefter.

SendChatMessageResult är svaret som returneras från att skicka ett meddelande, det innehåller ett ID, vilket är det unika ID:t för meddelandet.

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}`);

Lägg till den här koden i stället för kommentaren <SEND MESSAGE TO A CHAT THREAD> i client.js, uppdatera webbläsarfliken och kontrollera konsolen.

Message sent!, message id:<number>

Ta emot chattmeddelanden från en chatttråd

Med realtidssignalering kan du prenumerera på att lyssna efter nya inkommande meddelanden och uppdatera de aktuella meddelandena i minnet i enlighet med detta. Azure Communication Services stöder en lista över händelser som du kan prenumerera på.

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

Lägg till den här koden i stället för <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> kommentar i client.js. Uppdatera webbläsarfliken. Du bör se ett meddelande Notification chatMessageReceivedi konsolen .

Du kan också hämta chattmeddelanden genom att avsöka listMessages metoden med angivna intervall.


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

Lägg till den här koden i stället för kommentaren <LIST MESSAGES IN A CHAT THREAD> i client.js. Uppdatera fliken. I konsolen bör du hitta listan över meddelanden som skickas i den här chatttråden.

listMessages returnerar olika typer av meddelanden som kan identifieras av chatMessage.type.

Mer information finns i Meddelandetyper.

Lägga till en användare som deltagare i chatttråden

När en chatttråd har skapats kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst till att skicka meddelanden till chatttråden och lägga till/ta bort andra deltagare.

Innan du anropar addParticipants metoden kontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren. Användaren behöver den åtkomsttoken för att initiera chattklienten.

addParticipantsRequest beskriver begärandeobjektet där participants de deltagare som ska läggas till i chatttråden visas.

  • id, krävs, är kommunikationsidentifieraren som ska läggas till i chatttråden.
  • displayName, valfritt, är visningsnamnet för tråddeltagaren.
  • shareHistoryTime, valfritt, är den tid från vilken chatthistoriken delas med deltagaren. Om du vill dela historiken sedan chatttråden startades ställer du in den här egenskapen på ett datum som är lika med eller mindre än tiden då tråden skapades. Om du vill dela någon historik tidigare än när deltagaren lades till anger du det till aktuellt datum. Om du vill dela partiell historik anger du det datum som du väljer.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Ersätt NEW_PARTICIPANT_USER_ID med ett nytt användar-ID Lägg till den här koden i stället för kommentaren <ADD NEW PARTICIPANT TO THREAD> i client.js

Lista användare i en chatttråd

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

Lägg till den här koden i stället för kommentaren <LIST PARTICIPANTS IN A THREAD> i client.js, uppdatera webbläsarfliken och kontrollera konsolen. Du bör se information om användare i en tråd.

Ta bort användare från en chatttråd

På samma sätt som när du lägger till en deltagare kan du ta bort deltagare från en chatttråd. För att kunna ta bort måste du spåra ID:t för de deltagare som du har lagt till.

Använd removeParticipant metoden där participant är kommunikationsanvändaren som ska tas bort från tråden.


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

Ersätt PARTICIPANT_ID med ett användar-ID som användes i föregående steg (<NEW_PARTICIPANT_USER_ID>). Lägg till den här koden i stället för kommentaren <REMOVE PARTICIPANT FROM THREAD> i client.js.

Prenumerera på anslutningsstatus för realtidsmeddelanden

Prenumeration på händelser realTimeNotificationConnected och realTimeNotificationDisconnected gör att du kan veta när anslutningen till anropsservern är aktiv.

// 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
});

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Innan du kommer igång måste du:

Konfigurera

Skapa ett nytt Python-program

Öppna terminalen eller kommandofönstret, skapa en ny katalog för din app och gå till den.

mkdir chat-quickstart && cd chat-quickstart

Använd en textredigerare för att skapa en fil med namnet start-chat.py i projektets rotkatalog. Lägg till strukturen för programmet, inklusive grundläggande undantagshantering. I följande avsnitt lägger du till all källkod för den här snabbstarten i den här filen.

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)

Installera SDK

Använd följande kommando för att installera SDK:et:


pip install azure-communication-chat

Objektmodell

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för Python.

Namn Beskrivning
ChatClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta och ta bort trådar.
ChatThreadClient Den här klassen behövs för chatttrådsfunktionen. Du hämtar en instans via ChatClientoch använder den för att skicka, ta emot, uppdatera och ta bort meddelanden. Du kan också använda den för att lägga till, ta bort och hämta användare och skicka skrivmeddelanden och läskvitton.

Skapa en chattklient

Om du vill skapa en chattklient använder du slutpunkten för Communication Services och åtkomsttoken som du genererade som en del av nödvändiga steg.

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

Den här snabbstarten omfattar inte att skapa en tjänstnivå för att hantera token för chattprogrammet, men det rekommenderas. Mer information finns i avsnittet "Chattarkitektur" i Chattbegrepp.

Starta en chatttråd

create_chat_thread Använd metoden för att skapa en chatttråd.

  • Använd topic för att ge tråden ett ämne. Du kan uppdatera ämnet när chatttråden har skapats med hjälp update_thread av funktionen .
  • Använd thread_participants för att visa en lista över de ChatParticipant som ska läggas till i chatttråden. Tar ChatParticipant CommunicationUserIdentifier typen som user.

CreateChatThreadResult är resultatet som returneras från att skapa en tråd. Du kan använda den för att hämta chatttråden id som skapades. Detta id kan sedan användas för att hämta ett ChatThreadClient objekt med hjälp get_chat_thread_client av metoden . Du kan använda ChatThreadClient för att utföra andra chattåtgärder i den här chatttråden.

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)

Hämta en chatttrådsklient

Metoden get_chat_thread_client returnerar en trådklient för en tråd som redan finns. Du kan använda den för att utföra åtgärder på den skapade tråden. Du kan till exempel lägga till deltagare och skicka meddelanden. thread_id är det unika ID:t för den befintliga chatttråden.

Du kan använda ChatThreadClient för att utföra andra chattåtgärder i den här chatttråden.

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

Visa en lista över alla chatttrådar

Metoden list_chat_threads returnerar en iterator av typen ChatThreadItem.

  • Använd start_time för att ange den tidigaste tidpunkten för att hämta chatttrådar.
  • Använd results_per_page för att ange det maximala antalet chatttrådar som returneras per sida.

En iterator för [ChatThreadItem] är svaret som returneras från listtrådar.

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)

Skicka ett meddelande till en chatttråd

send_message Använd metoden för att skicka ett meddelande till en chatttråd som du nyss skapade, identifierad av thread_id.

  • Använd content för att ange innehållet i chattmeddelandet.
  • Använd chat_message_type för att ange meddelandeinnehållstypen. Möjliga värden är text och html. Om du inte anger något värde är textstandardvärdet .
  • Använd sender_display_name för att ange avsändarens visningsnamn.
  • Om metadata du vill kan du inkludera ytterligare data som du vill skicka tillsammans med meddelandet. Det här fältet innehåller en mekanism för utvecklare att utöka chattmeddelandefunktionerna och lägga till anpassad information för ditt användningsfall. När du till exempel delar en fillänk i meddelandet kanske du vill lägga till "hasAttachment:true" i metadata så att mottagarens program kan parsa det och visa därefter.

SendChatMessageResult är svaret som returneras från att skicka ett meddelande. Den innehåller ett ID, vilket är det unika ID:t för meddelandet.

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)

Ta emot chattmeddelanden från en chatttråd

Du kan hämta chattmeddelanden genom att avsöka list_messages metoden med angivna intervall.

  • Använd results_per_page för att ange det maximala antalet meddelanden som ska returneras per sida.
  • Använd start_time för att ange den tidigaste tidpunkten för att hämta meddelanden.

En iterator för är svaret som returneras från listningsmeddelanden [ChatMessage] .

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 returnerar den senaste versionen av meddelandet, inklusive eventuella ändringar eller borttagningar som har hänt med meddelandet med hjälp update_message av och delete_message. För borttagna meddelanden ChatMessage.deleted_on returnerar ett datetime värde som anger när meddelandet togs bort. För redigerade meddelanden ChatMessage.edited_on returnerar ett datetime värde som anger när meddelandet redigerades. Du kan komma åt den ursprungliga tiden då meddelandet skapades med hjälp ChatMessage.created_onav , som kan användas för att beställa meddelandena.

list_messages returnerar olika typer av meddelanden, som kan identifieras av ChatMessage.type.

Mer information finns i Meddelandetyper.

Skicka läskvitto

Du använder send_read_receipt metoden för att publicera en läskvittohändelse i en tråd för en användares räkning.

  • Använd message_id för att ange ID för det senaste meddelandet som lästs av den aktuella användaren.
content='hello world'

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

Lägga till en användare som deltagare i chatttråden

När du skapar en chatttråd kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst för att kunna skicka meddelanden till chatttråden och lägga till eller ta bort andra deltagare. Innan du anropar add_participants metoden kontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren. Användaren behöver åtkomsttoken för att initiera chattklienten.

Du kan lägga till en eller flera användare i chatttråden add_participants med hjälp av metoden, förutsatt att en ny åtkomsttoken och identitet är tillgänglig för alla användare.

A list(tuple(ChatParticipant, CommunicationError)) returneras. När deltagaren har lagts till förväntas en tom lista. Om du stöter på ett fel när du lägger till en deltagare fylls listan med de misslyckade deltagarna, tillsammans med det fel som påträffades.

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)

Lista tråddeltagare i en chatttråd

På samma sätt som när du lägger till en deltagare kan du även lista deltagare från en tråd.

Använd list_participants för att hämta deltagarna i tråden. Båda följande kommandon är valfria:

  • Använd results_per_page för att ange det maximala antalet deltagare som ska returneras per sida.
  • Använd skip för att hoppa över deltagare upp till en angiven position i svaret.

En iterator för [ChatParticipant] är svaret som returneras från en lista över deltagare.

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)

Kör koden

Kör programmet från programkatalogen python med kommandot .

python start-chat.py

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Konfigurera

Skapa ett nytt Java-program

Öppna terminalen eller kommandofönstret och gå till katalogen där du vill skapa java-programmet. Kör kommandot nedan för att generera Java-projektet från mallen maven-archetype-quickstart.

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

Du kommer att märka att "generera"-målet skapade en katalog med samma namn som artifactId. Under den här katalogen src/main/java directory innehåller projektets källkod, src/test/java katalogen innehåller testkällan och pom.xml-filen är projektets projektobjektmodell eller POM.

Uppdatera programmets POM-fil för att använda Java 8 eller senare:

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

Lägg till paketreferenserna för Chat SDK

I POM-filen refererar du till azure-communication-chat paketet med chatt-API:erna:

<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 autentisering måste klienten referera azure-communication-common till paketet:

<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

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för Java.

Namn Beskrivning
ChatClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta och ta bort trådar.
ChatAsyncClient Den här klassen behövs för asynkrona chattfunktioner. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta och ta bort trådar.
ChatThreadClient Den här klassen behövs för chatttrådsfunktionen. Du hämtar en instans via ChatClient och använder den för att skicka/ta emot/uppdatera/ta bort meddelanden, lägga till/ta bort/hämta användare, skicka skrivmeddelanden och läsa kvitton.
ChatThreadAsyncClient Den här klassen behövs för funktionen asynkron chatttråd. Du hämtar en instans via ChatAsyncClient och använder den för att skicka/ta emot/uppdatera/ta bort meddelanden, lägga till/ta bort/hämta användare, skicka skrivmeddelanden och läskvitton.

Skapa en chattklient

Om du vill skapa en chattklient använder du slutpunkten för kommunikationstjänsten och åtkomsttoken som genererades som en del av nödvändiga steg. Med användaråtkomsttoken kan du skapa klientprogram som autentiserar direkt till Azure Communication Services. När du har genererat dessa token på servern skickar du tillbaka dem till en klientenhet. Du måste använda klassen CommunicationTokenCredential från Common SDK för att skicka token till chattklienten.

Läs mer om chattarkitektur

När du lägger till importinstruktionerna ska du bara lägga till importer från namnrymderna com.azure.communication.chat.models och inte från namnområdet com.azure.communication.chat.implementation. I filen App.java som genererades via Maven kan du använda följande kod till att börja med:

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

Starta en chatttråd

createChatThread Använd metoden för att skapa en chatttråd. createChatThreadOptions används för att beskriva trådbegäran.

  • Använd parametern topic för konstruktorn för att ge ett ämne till den här chatten. Ämnet kan uppdateras när chatttråden har skapats med hjälp av UpdateThread funktionen .
  • Använd participants för att lista de tråddeltagare som ska läggas till i tråden. ChatParticipant tar den användare som du skapade i snabbstarten för användaråtkomsttoken .

CreateChatThreadResult är svaret som returneras från skapandet av en chatttråd. Den innehåller en getChatThread() metod som returnerar det ChatThread objekt som kan användas för att hämta trådklienten ChatThreadClient som du kan hämta för att utföra åtgärder i den skapade tråden: lägga till deltagare, skicka meddelande osv. Objektet ChatThread innehåller också metoden getId() som hämtar trådens unika ID.

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

Lista chatttrådar

listChatThreads Använd metoden för att hämta en lista över befintliga chatttrådar.

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

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

Hämta en chatttrådsklient

Metoden getChatThreadClient returnerar en trådklient för en tråd som redan finns. Den kan användas för att utföra åtgärder i den skapade tråden: lägga till deltagare, skicka meddelande osv. chatThreadId är det unika ID:t för den befintliga chatttråden.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Skicka ett meddelande till en chatttråd

sendMessage Använd metoden för att skicka ett meddelande till den tråd som du skapade, identifierad av chatThreadId. sendChatMessageOptions används för att beskriva chattmeddelandeförfrågan.

  • Använd content för att ange innehållet i chattmeddelandet.
  • Använd type för att ange innehållstypen för chattmeddelanden, TEXT eller HTML.
  • Använd senderDisplayName för att ange avsändarens visningsnamn.
  • Om metadata du vill kan du inkludera ytterligare data som du vill skicka tillsammans med meddelandet. Det här fältet innehåller en mekanism för utvecklare att utöka chattmeddelandefunktionerna och lägga till anpassad information för ditt användningsfall. När du till exempel delar en fillänk i meddelandet kanske du vill lägga hasAttachment:true till metadata så att mottagarens program kan parsa det och visa det.

Svaret sendChatMessageResult innehåller ett id, vilket är det unika ID:t för meddelandet.

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

Ta emot chattmeddelanden från en chatttråd

Du kan hämta chattmeddelanden genom att avsöka listMessages metoden på chatttrådsklienten med angivna intervall.

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

listMessages returnerar den senaste versionen av meddelandet, inklusive eventuella ändringar eller borttagningar som hände med meddelandet med hjälp av .editMessage() och .deleteMessage(). För borttagna meddelanden chatMessage.getDeletedOn() returnerar ett datetime-värde som anger när meddelandet togs bort. För redigerade meddelanden chatMessage.getEditedOn() returnerar en datetime som anger när meddelandet redigerades. Den ursprungliga tiden då meddelandet skapades kan nås med hjälp av chatMessage.getCreatedOn()och kan användas för att beställa meddelandena.

Läs mer om meddelandetyper här: Meddelandetyper.

Skicka läskvitto

sendReadReceipt Använd metoden för att publicera en läskvittohändelse i en chatttråd för en användares räkning. chatMessageId är det unika ID:t för chattmeddelandet som lästes.

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

Visa en lista över chattdeltagare

Använd listParticipants för att hämta en sidig samling som innehåller deltagarna i chatttråden som identifierats av chatThreadId.

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

Lägga till en användare som deltagare i chatttråden

När en chatttråd har skapats kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst till att skicka meddelanden till chatttråden och lägga till/ta bort andra deltagare. Du måste börja med att hämta en ny åtkomsttoken och identitet för den användaren. Innan du anropar metoden addParticipants kontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren. Användaren behöver den åtkomsttoken för att initiera chattklienten.

addParticipants Använd metoden för att lägga till deltagare i tråden.

  • communicationIdentifier, obligatoriskt, är Den CommunicationIdentifier som du har skapat av CommunicationIdentityClient i snabbstarten för användaråtkomsttoken .
  • displayName, valfritt, är visningsnamnet för tråddeltagaren.
  • shareHistoryTime, valfritt, är den tid från vilken chatthistoriken delas med deltagaren. Om du vill dela historiken sedan chatttråden startades ställer du in den här egenskapen på ett datum som är lika med eller mindre än tiden då tråden skapades. Om du vill dela någon historik tidigare än när deltagaren lades till anger du det till aktuellt datum. Om du vill dela partiell historik anger du det till det datum som krävs.
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);

Kör koden

Navigera till katalogen som innehåller pom.xml-filen och kompilera projektet med hjälp av följande mvn kommando.

mvn compile

Skapa sedan paketet.

mvn package

Kör följande mvn kommando för att köra appen.

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

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Innan du kommer igång måste du:

  • Skapa ett Azure-konto med en aktiv prenumeration. Mer information finns i Skapa ett konto kostnadsfritt.

  • Installera Android Studio, vi kommer att använda Android Studio för att skapa ett Android-program för snabbstarten för att installera beroenden.

  • Skapa en Azure Communication Services-resurs. Mer information finns i Skapa en Azure Communication Services-resurs. Du måste registrera resursslutpunkten och anslutningssträng för den här snabbstarten.

  • Skapa två Communication Services-användare och ge dem en användaråtkomsttoken. Se till att ange omfånget till chatt och notera tokensträngen och user_id strängen. I den här snabbstarten skapar vi en tråd med en första deltagare och lägger sedan till en andra deltagare i tråden. Du kan också använda Azure CLI och köra kommandot nedan med din anslutningssträng för att skapa en användare och en åtkomsttoken.

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

    Mer information finns i Använda Azure CLI för att skapa och hantera åtkomsttoken.

Konfigurera

Skapa ett nytt Android-program

  1. Öppna Android Studio och välj Create a new project.
  2. I nästa fönster väljer du Empty Activity som projektmall.
  3. När du väljer alternativ anger du ChatQuickstart som projektnamn.
  4. Klicka på nästa och välj den katalog där du vill att projektet ska skapas.

Installera biblioteken

Vi använder Gradle för att installera de nödvändiga kommunikationstjänsternas beroenden. Från kommandoraden navigerar du i projektets ChatQuickstart rotkatalog. Öppna appens build.gradle-fil och lägg till följande beroenden i ChatQuickstart målet:

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

https://search.maven.org/artifact/com.azure.android/azure-communication-common Se och https://search.maven.org/artifact/com.azure.android/azure-communication-chat för de senaste versionsnumren.

Exkludera metafiler i paketeringsalternativ i root 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")
    }
}

(Alternativ) Så här installerar du bibliotek via Maven

Om du vill importera biblioteket till projektet med hjälp av Maven-byggsystemet lägger du till det i dependencies avsnittet i appens pom.xml fil och anger dess artefakt-ID och den version som du vill använda:

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

Skapa en Azure-funktion

Mer information finns i Azure-funktionsintegrering . Vi rekommenderar starkt att du integrerar med Azure Function för att undvika hårdkodade programparametrar.

Konfigurera programkonstanter:

Skapa en klass ApplicationConstants som lagrar alla programkonstanter:

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;
}

Konfigurera platshållarna

Öppna och redigera filen MainActivity.java. I den här snabbstarten lägger vi till koden MainActivityi och visar utdata i konsolen. Den här snabbstarten handlar inte om att skapa ett användargränssnitt. Längst upp i filen importerar du Azure Communication Common, Azure Communication Chatoch andra systembibliotek:

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;

Kopiera följande kod till klassen MainActivity i filen MainActivity.java:

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

Initiera programparametrar

Kommentar

Initiering ApplicationConstants måste läggas till MainActivity.java om något av följande villkor uppfylls: 1. Funktionen för push-meddelanden är INTE aktiverad. 2. Versionen för Azure Communication Chat-biblioteket för Android är < "2.0.0". I annat fall kan du läsa steg 11 i Android-push-meddelanden. Se exempelappen för den SDK-version som du använder som referens.

ACS_ENDPOINToch FIRST_USER_ID FIRST_USER_ACCESS_TOKEN returneras från att anropa Azure Function. Mer information finns i Azure-funktionsintegrering . Vi använder svaret från att anropa Azure Function för att initiera listan med parametrar:

  • ACS_ENDPOINT: slutpunkten för din Communication Services-resurs.
  • FIRST_USER_ID och SECOND_USER_ID: giltiga användar-ID:t för Communication Services som genereras av din Communication Services-resurs.
  • FIRST_USER_ACCESS_TOKEN: åtkomsttoken för communication Services för <FIRST_USER_ID>.

Kodblock för att initiera programparametrar genom att anropa 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);
    }

Skapa en chattklient

Ersätt kommentaren <CREATE A CHAT CLIENT> med följande kod (placera importinstruktionerna överst i filen):

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

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för JavaScript.

Namn Beskrivning
ChatClient/ChatAsyncClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta, ta bort trådar och prenumerera på chatthändelser.
ChatThreadClient/ChatThreadAsyncClient Den här klassen behövs för chatttrådsfunktionen. Du hämtar en instans via ChatClient och använder den för att skicka/ta emot/uppdatera/ta bort meddelanden, lägga till/ta bort/hämta användare, skicka skrivmeddelanden och läsa kvitton.

Starta en chatttråd

Vi använder vår ChatAsyncClient för att skapa en ny tråd med en första användare.

Ersätt kommentaren <CREATE A CHAT THREAD> med följande kod:

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

Hämta en chatttrådsklient

Nu när vi har skapat en chatttråd får vi en ChatThreadAsyncClient för att utföra åtgärder i tråden. Ersätt kommentaren <CREATE A CHAT THREAD CLIENT> med följande kod:

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

Skicka ett meddelande till en chatttråd

Vi skickar ett meddelande till den tråden nu.

Ersätt kommentaren <SEND A MESSAGE> med följande kod:

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

Ta emot chattmeddelanden från en chatttråd

Realtidsmeddelanden

Med realtidssignalering kan du prenumerera på nya inkommande meddelanden och uppdatera de aktuella meddelandena i minnet i enlighet med detta. Azure Communication Services stöder en lista över händelser som du kan prenumerera på.

Ersätt kommentaren <RECEIVE CHAT MESSAGES> med följande kod (placera importinstruktionerna överst i filen):


// 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
    
});

Viktigt!

Känt problem: När du använder Android Chat och Calling SDK tillsammans i samma program fungerar inte Chat SDK:s realtidsaviseringar. Du kan få problem med att lösa ett beroende. Medan vi arbetar med en lösning kan du inaktivera funktionen för realtidsaviseringar genom att lägga till följande beroendeinformation i appens build.gradle-fil och i stället avsöka Api:et GetMessages för att visa inkommande meddelanden för användare.

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'

Observera med ovanstående uppdatering, om programmet försöker röra något av meddelande-API:et som chatAsyncClient.startRealtimeNotifications() eller chatAsyncClient.addEventHandler(), kommer det att uppstå ett körningsfel.

Push-meddelanden

Mer information finns i Android-push-meddelanden .

Lägga till en användare som deltagare i chatttråden

Ersätt kommentaren <ADD A USER> med följande kod:

// 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);

Visa en lista över användare i en tråd

Ersätt kommentaren <LIST USERS> med följande kod (placera importinstruktionerna överst i filen):

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
});

Ta bort användare från en chatttråd

Vi tar bort den andra användaren från tråden nu.

Ersätt kommentaren <REMOVE A USER> med följande kod:

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

Skicka ett skrivmeddelande

Ersätt kommentaren <SEND A TYPING NOTIFICATION> med följande kod:

chatThreadAsyncClient.sendTypingNotification().get();

Skicka ett läskvitto

Vi skickar läskvitto för meddelandet som skickades ovan.

Ersätt kommentaren <SEND A READ RECEIPT> med följande kod:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Visa en lista över läskvitton

Ersätt kommentaren <READ RECEIPTS> med följande kod:

// 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
});

Kör koden

I Android Studio trycker du på knappen Kör för att skapa och köra projektet. I konsolen kan du visa utdata från koden och loggningsutdata från ChatClient.

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Innan du kommer igång måste du:

Konfigurera

Skapa ett nytt C#-program

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet new kommandot för att skapa en ny konsolapp med namnet ChatQuickstart. Det här kommandot skapar ett enkelt "Hello World" C#-projekt med en enda källfil: Program.cs.

dotnet new console -o ChatQuickstart

Ändra katalogen till den nyligen skapade appmappen dotnet build och använd kommandot för att kompilera programmet.

cd ChatQuickstart
dotnet build

Installera -paketet

Installera Azure Communication Chat SDK för .NET

dotnet add package Azure.Communication.Chat

Objektmodell

Följande klasser hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för C#.

Namn Beskrivning
ChatClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta och ta bort trådar.
ChatThreadClient Den här klassen behövs för chatttrådsfunktionen. Du får en instans via ChatClient och använder den för att skicka/ta emot/uppdatera/ta bort meddelanden, lägga till/ta bort/hämta deltagare, skicka skrivmeddelanden och läskvitton.

Skapa en chattklient

Om du vill skapa en chattklient använder du slutpunkten för Communication Services och åtkomsttoken som genererades som en del av de nödvändiga stegen. Du måste använda CommunicationIdentityClient klassen från Identity SDK för att skapa en användare och utfärda en token för att skicka till chattklienten.

Läs mer om användaråtkomsttoken.

Den här snabbstarten beskriver inte hur du skapar en tjänstnivå för att hantera token för chattprogrammet, även om det rekommenderas. Läs mer om chattarkitektur

Kopiera följande kodfragment och klistra in i källfilen: Program.cs

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);
        }
    }
}

Starta en chatttråd

createChatThread Använd metoden i chatClient för att skapa en chatttråd

  • Använd topic för att ge ett ämne till den här chatten; Ämnet kan uppdateras när chatttråden har skapats med hjälp av UpdateTopic funktionen .
  • Använd participants egenskapen för att skicka en lista över ChatParticipant objekt som ska läggas till i chatttråden. Objektet ChatParticipant initieras med ett CommunicationIdentifier objekt. CommunicationIdentifier kan vara av typen CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier eller PhoneNumberIdentifier. Om du till exempel vill hämta ett CommunicationIdentifier objekt måste du skicka ett åtkomst-ID som du skapade genom att följa anvisningarna för att skapa en användare

Svarsobjektet från createChatThread metoden innehåller chatThread information. Om du vill interagera med chatttrådsåtgärder som att lägga till deltagare, skicka ett meddelande, ta bort ett meddelande osv. måste en chatThreadClient klientinstans instans instansieras med hjälp av GetChatThreadClient -metoden på ChatClient klienten.

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;

Hämta en chatttrådsklient

Metoden GetChatThreadClient returnerar en trådklient för en tråd som redan finns. Den kan användas för att utföra åtgärder i den skapade tråden: lägga till medlemmar, skicka meddelande osv. threadId är det unika ID:t för den befintliga chatttråden.

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

Visa en lista över alla chatttrådar

Använd GetChatThreads för att hämta alla chatttrådar som användaren är en del av.

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

Skicka ett meddelande till en chatttråd

Använd SendMessage för att skicka ett meddelande till en tråd.

  • Använd content för att ange innehållet för meddelandet, det krävs.
  • Använd type för innehållstypen för meddelandet, till exempel "Text" eller "Html". Om det inte anges anges kommer "Text" att anges.
  • Använd senderDisplayName för att ange avsändarens visningsnamn. Om inte anges anges en tom sträng.
  • Om metadata du vill kan du inkludera ytterligare data som du vill skicka tillsammans med meddelandet. Det här fältet innehåller en mekanism för utvecklare att utöka chattmeddelandefunktionerna och lägga till anpassad information för ditt användningsfall. När du till exempel delar en fillänk i meddelandet kanske du vill lägga till "hasAttachment:true" i metadata så att mottagarens program kan parsa det och visa därefter.
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;

Ta emot chattmeddelanden från en chatttråd

Du kan hämta chattmeddelanden genom att avsöka GetMessages metoden på chatttrådsklienten med angivna intervall.

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

GetMessages tar en valfri DateTimeOffset parameter. Om förskjutningen har angetts får du meddelanden som har tagits emot, uppdaterats eller tagits bort efter den. Observera att meddelanden som tagits emot före förskjutningen men som redigerats eller tagits bort efter det också kommer att returneras.

GetMessages returnerar den senaste versionen av meddelandet, inklusive eventuella ändringar eller borttagningar som hände med meddelandet med hjälp av UpdateMessage och DeleteMessage. För borttagna meddelanden chatMessage.DeletedOn returnerar ett datetime-värde som anger när meddelandet togs bort. För redigerade meddelanden chatMessage.EditedOn returnerar en datetime som anger när meddelandet redigerades. Den ursprungliga tiden då meddelandet skapades kan nås med hjälp av chatMessage.CreatedOnoch kan användas för att beställa meddelandena.

GetMessages returnerar olika typer av meddelanden som kan identifieras av chatMessage.Type. Följande typer är:

  • Text: Vanligt chattmeddelande som skickas av en trådmedlem.

  • Html: Ett formaterat textmeddelande. Observera att Communication Services-användare för närvarande inte kan skicka RichText-meddelanden. Den här meddelandetypen stöds av meddelanden som skickas från Teams-användare till Communication Services-användare i Teams Interop-scenarier.

  • TopicUpdated: Systemmeddelande som anger att ämnet har uppdaterats. (skrivskyddat)

  • ParticipantAdded: Systemmeddelande som anger att en eller flera deltagare har lagts till i chatttråden. (skrivskyddat)

  • ParticipantRemoved: Systemmeddelande som anger att en deltagare har tagits bort från chatttråden.

Mer information finns i Meddelandetyper.

Lägga till en användare som deltagare i chatttråden

När en tråd har skapats kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst för att kunna skicka meddelanden till tråden och lägga till/ta bort andra deltagare. Innan du anropar AddParticipantskontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren. Användaren behöver den åtkomsttoken för att initiera chattklienten.

Använd AddParticipants för att lägga till en eller flera deltagare i chatttråden. Följande är attribut som stöds för varje tråddeltagare:

  • communicationUser, obligatoriskt, är identiteten för tråddeltagaren.
  • displayName, valfritt, är visningsnamnet för tråddeltagaren.
  • shareHistoryTime, valfritt, tid från vilken chatthistoriken delas med deltagaren.
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);

Hämta tråddeltagare

Använd GetParticipants för att hämta deltagarna i chatttråden.

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

Skicka läskvitto

Använd SendReadReceipt för att meddela andra deltagare att meddelandet läss av användaren.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Kör koden

Kör programmet från programkatalogen dotnet run med kommandot .

dotnet run

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Innan du kommer igång måste du:

  • Skapa ett Azure-konto med en aktiv prenumeration. Mer information finns i Skapa ett konto kostnadsfritt.

  • Installera Xcode och CocoaPods. Du använder Xcode för att skapa ett iOS-program för snabbstarten och CocoaPods för att installera beroenden.

  • Skapa en Azure Communication Services-resurs. Mer information finns i Snabbstart: Skapa och hantera Communication Services-resurser. Du måste registrera resursslutpunkten och anslutningssträng för den här snabbstarten.

  • Skapa två användare i Azure Communication Services och ge dem en användaråtkomsttoken. Se till att ange omfånget till chatt och notera tokensträngen samt user_id strängen. I den här snabbstarten skapar du en tråd med en första deltagare och lägger sedan till en andra deltagare i tråden. Du kan också använda Azure CLI och köra kommandot nedan med din anslutningssträng för att skapa en användare och en åtkomsttoken.

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

    Mer information finns i Använda Azure CLI för att skapa och hantera åtkomsttoken.

Konfigurera

Skapa ett nytt iOS-program

Öppna Xcode och välj Skapa ett nytt Xcode-projekt. Välj sedan iOS som plattform och App för mallen.

Som projektnamn anger du ChatQuickstart. Välj sedan Storyboard som gränssnitt, UIKit App Delegate som livscykel och Swift som språk.

Välj Nästa och välj den katalog där du vill att projektet ska skapas.

Installera biblioteken

Använd CocoaPods för att installera de nödvändiga kommunikationstjänsternas beroenden.

Från kommandoraden går du in i rotkatalogen för ChatQuickstart iOS-projektet. Skapa en Podfile med följande kommando: pod init.

Öppna Podfile och lägg till följande beroenden i ChatQuickstart målet:

pod 'AzureCommunicationChat', '~> 1.3.6'

Installera beroendena med följande kommando: pod install. Observera att detta också skapar en Xcode-arbetsyta.

När du har kört pod installöppnar du projektet igen i Xcode genom att välja den nyligen skapade .xcworkspace.

Konfigurera platshållarna

Öppna arbetsytan ChatQuickstart.xcworkspace i Xcode och öppna ViewController.swiftsedan .

I den här snabbstarten lägger du till koden i viewControlleroch visar utdata i Xcode-konsolen. Den här snabbstarten handlar inte om att skapa ett användargränssnitt i iOS.

Överst i viewController.swiftimporterar du biblioteken AzureCommunication och AzureCommunicatonChat :

import AzureCommunicationCommon
import AzureCommunicationChat

Kopiera följande kod till viewDidLoad() metoden 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)")
            }
        }
    }

I demonstrationssyfte använder vi en semafor för att synkronisera koden. I följande steg ersätter du platshållarna med exempelkod med hjälp av Azure Communication Services Chat-biblioteket.

Skapa en chattklient

Om du vill skapa en chattklient använder du slutpunkten för Communication Services och åtkomsttoken som genererades som en del av de nödvändiga stegen.

Läs mer om användaråtkomsttoken.

Den här snabbstarten beskriver inte hur du skapar en tjänstnivå för att hantera token för chattprogrammet, även om det rekommenderas. Läs mer om chattarkitektur

Ersätt kommentaren <CREATE A CHAT CLIENT> med kodfragmentet nedan:

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
)

Ersätt <ACS_RESOURCE_ENDPOINT> med slutpunkten för din Azure Communication Services-resurs. Ersätt <ACCESS_TOKEN> med en giltig kommunikationstjänståtkomsttoken.

Objektmodell

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services Chat SDK för iOS.

Namn Beskrivning
ChatClient Den här klassen behövs för chattfunktionen. Du instansierar den med din prenumerationsinformation och använder den för att skapa, hämta, ta bort trådar och prenumerera på chatthändelser.
ChatThreadClient Den här klassen behövs för chatttrådsfunktionen. Du hämtar en instans via ChatClientoch använder den för att skicka, ta emot, uppdatera och ta bort meddelanden. Du kan också använda den för att lägga till, ta bort och hämta användare, skicka skrivmeddelanden och läskvitton.

Starta en chatttråd

CreateChatThreadResult är svaret som returneras från skapandet av en chatttråd. Den innehåller en chatThread egenskap som är objektet ChatThreadProperties . Det här objektet innehåller threadId som kan användas för att hämta en ChatThreadClient för att utföra åtgärder på den skapade tråden: lägga till deltagare, skicka meddelande osv.

Ersätt kommentaren <CREATE A CHAT THREAD> med kodfragmentet nedan:

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

Ersätt <USER_ID> med ett giltigt användar-ID för Communication Services.

Du använder en semafor här för att vänta på slutförandehanteraren innan du fortsätter. I senare steg använder threadId du från svaret som returneras till slutförandehanteraren.

Visa en lista över alla chatttrådar

När vi har skapat en chatttråd kan vi lista alla chatttrådar genom att anropa metoden på listChatThreads ChatClient. Ersätt kommentaren <LIST ALL CHAT THREADS> med följande kod:

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

Hämta en chatttrådsklient

Metoden createClient returnerar en ChatThreadClient för en tråd som redan finns. Den kan användas för att utföra åtgärder i den skapade tråden: lägga till deltagare, skicka meddelande osv. threadId är det unika ID:t för den befintliga chatttråden.

Ersätt kommentaren <GET A CHAT THREAD CLIENT> med följande kod:

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

Skicka ett meddelande till en chatttråd

send Använd metoden för att skicka ett meddelande till en tråd som identifieras av threadId.

SendChatMessageRequest används för att beskriva meddelandebegäran:

  • Använd content för att ange innehållet i chattmeddelandet
  • Använd senderDisplayName för att ange avsändarens visningsnamn
  • Använd type för att ange meddelandetypen, till exempel "text" eller "html"
  • Om metadata du vill kan du inkludera ytterligare data som du vill skicka tillsammans med meddelandet. Det här fältet innehåller en mekanism för utvecklare att utöka chattmeddelandefunktionerna och lägga till anpassad information för ditt användningsfall. När du till exempel delar en fillänk i meddelandet kanske du vill lägga till "hasAttachment:true" i metadata så att mottagarens program kan parsa det och visa därefter.

SendChatMessageResult är svaret som returneras från att skicka ett meddelande, det innehåller ett ID, vilket är det unika ID:t för meddelandet.

Ersätt kommentaren <SEND A MESSAGE> med kodfragmentet nedan:

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

Skicka ett läskvitto

sendReadReceipt Använd metoden för att publicera en läskvittohändelse i en chatttråd för en användares räkning. messageId är det unika ID:t för chattmeddelandet som lästes.

Ersätt kommentaren <SEND A READ RECEIPT> med koden nedan:

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")
}

Ta emot chattmeddelanden från en chatttråd

Med realtidssignalering kan du prenumerera på att lyssna efter nya inkommande meddelanden och uppdatera de aktuella meddelandena i minnet i enlighet med detta. Azure Communication Services stöder en lista över händelser som du kan prenumerera på.

Ersätt kommentaren <RECEIVE MESSAGES> med koden nedan. När du har aktiverat meddelanden kan du prova att skicka nya meddelanden för att se ChatMessageReceivedEvents.

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

Du kan också hämta chattmeddelanden genom att avsöka listMessages metoden med angivna intervall. Se följande kodfragment för listMessages

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

Lägga till en användare som deltagare i chatttråden

När en tråd har skapats kan du sedan lägga till och ta bort användare från den. Genom att lägga till användare ger du dem åtkomst för att kunna skicka meddelanden till tråden och lägga till/ta bort andra deltagare. Innan du anropar addkontrollerar du att du har skaffat en ny åtkomsttoken och identitet för den användaren. Användaren behöver den åtkomsttoken för att initiera chattklienten.

add Använd metoden ChatThreadClient för att lägga till en eller flera deltagare i chatttråden. Följande är attribut som stöds för varje tråddeltagare:

  • id, obligatoriskt, är identiteten för tråddeltagaren.
  • displayName, valfritt, är visningsnamnet för tråddeltagaren.
  • shareHistoryTime, valfritt, tid från vilken chatthistoriken delas med deltagaren.

Ersätt kommentaren <ADD A USER> med följande kod:

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

Ersätt <USER_ID> med kommunikationstjänsternas användar-ID för den användare som ska läggas till.

Visa en lista över användare i en tråd

listParticipants Använd metoden för att hämta alla deltagare för en viss chatttråd.

Ersätt kommentaren <LIST USERS> med följande kod:

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

Push-meddelanden

Push-meddelanden meddelar klienter om inkommande meddelanden i en chatttråd i situationer där mobilappen inte körs i förgrunden. För närvarande stöds sändning av chatt-push-meddelanden med Notification Hub för IOS SDK i version 1.3.0. Mer information finns i artikeln Aktivera push-meddelanden i chattappen .

Kör koden

I Xcode trycker du på knappen Kör för att skapa och köra projektet. I konsolen kan du visa utdata från koden och loggningsutdata från ChatClient.

Obs! Ange Build Settings > Build Options > Enable Bitcode till No. För närvarande har AzureCommunicationChat SDK för iOS inte stöd för aktivering av bitkod. Följande GitHub-problem spårar detta.

Exempelkod

Hitta den färdiga koden för den här snabbstarten på GitHub.

Förutsättningar

Skapa användare

Slutför de här stegen i Power Automate med power automate-flödet öppet i redigeringsläge.

Så här lägger du till ett nytt steg i arbetsflödet med hjälp av anslutningsappen för Kommunikationstjänsters identitet:

  1. I designern går du till steget där du vill lägga till den nya åtgärden och väljer Nytt steg. Du kan också lägga till den nya åtgärden mellan stegen genom att flytta pekaren över pilen mellan dessa steg, välja plustecknet (+) och sedan välja Lägg till en åtgärd.

  2. I sökrutan Välj en åtgärd anger du Communication Services-identitet. I listan över åtgärder väljer du Skapa en användare.

    Screenshot that shows the Azure Communication Services Identity connector Create user action.

  3. Ange anslutningssträng. Om du vill hämta anslutningssträng-URL:en i Azure-portalen går du till Azure Communication Services-resursen. I resursmenyn väljer du Nycklar och sedan Anslut ionssträng. Välj kopieringsikonen för att kopiera anslutningssträng.

    Screenshot that shows the Keys pane for an Azure Communication Services resource.

  4. Ange ett namn på anslutningen.

  5. Välj Visa avancerade alternativ och välj sedan tokenomfånget. Åtgärden genererar en åtkomsttoken och dess förfallotid med det angivna omfånget. Den här åtgärden genererar också ett användar-ID som är en Kommunikationstjänster-användaridentitet.

    Screenshot that shows the Azure Communication Services Identity connector Create user action options.

  6. I Objekt för tokenomfattningar väljer du chatt.

    Screenshot that shows the Azure Communication Services Chat connector advanced options.

  7. Välj Skapa. Användar-ID och en åtkomsttoken visas.

Skapa en chatttråd

  1. Lägg till en ny åtgärd.

  2. I sökrutan Välj en åtgärd anger du Communication Services Chat. I listan över åtgärder väljer du Skapa chatttråd.

    Screenshot that shows the Azure Communication Services Chat connector Create a chat thread action.

  3. Ange URL:en för Kommunikationstjänsters slutpunkt. Om du vill hämta slutpunkts-URL:en i Azure-portalen går du till Azure Communication Services-resursen. I resursmenyn väljer du Nycklar och sedan Slutpunkt.

  4. Ange ett namn på anslutningen.

  5. Välj den åtkomsttoken som genererades i föregående avsnitt och lägg sedan till en beskrivning av chatttrådsämnet. Lägg till den skapade användaren och ange ett namn för deltagaren.

    Screenshot that shows the Azure Communication Services Chat connector Create chat thread action dialog.

Skicka ett meddelande

  1. Lägg till en ny åtgärd.

  2. I sökrutan Välj en åtgärd anger du Communication Services Chat. I listan över åtgärder väljer du Skicka meddelande till chatttråd.

    Screenshot that shows the Azure Communication Services Chat connector Send chat message action.

  3. Ange åtkomsttoken, tråd-ID, innehåll och namn.

    Screenshot that shows the Azure Communication Services Chat connector Send chat message action dialog.

Lista chatttrådsmeddelanden

Så här kontrollerar du att du har skickat ett meddelande korrekt:

  1. Lägg till en ny åtgärd.

  2. I sökrutan Välj en åtgärd anger du Communication Services Chat. I listan över åtgärder väljer du Lista chatttrådsmeddelanden.

    Screenshot that shows the Azure Communication Services Chat connector List chat messages action.

  3. Ange åtkomsttoken och tråd-ID:t.

    Screenshot that shows the Azure Communication Services Chat connector List chat messages action dialog.

Testa logikappen

Om du vill starta arbetsflödet manuellt går du till verktygsfältet designer och väljer Kör. Arbetsflödet skapar en användare, utfärdar en åtkomsttoken för användaren och tar sedan bort token och tar bort användaren. Mer information finns i Så här kör du arbetsflödet.

Välj nu Lista chatttrådsmeddelanden. I åtgärdens utdata söker du efter meddelandet som skickades.

Screenshot that shows the Azure Communication Services Chat connector Send chat message action results.

Rensa arbetsflödesresurser

Om du vill rensa logikappens arbetsflöde och relaterade resurser kan du läsa om hur du rensar Logic Apps-resurser.

Rensa resurser

Om du vill rensa och ta bort en Communication Services-prenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort. Läs mer om att rensa resurser.

Nästa steg

I den här snabbstarten lärde du dig att:

  • Skapa en chattklient
  • Skapa en tråd med två användare
  • Skicka ett meddelande till tråden
  • Ta emot meddelanden från en tråd
  • Ta bort användare från en tråd

Prova chatthjälteappen

Du kanske också vill: