Guida introduttiva: Aggiungere chat all'app

  • Articolo

Per iniziare a usare Servizi di comunicazione di Azure, usare Chat SDK di Servizi di comunicazione per aggiungere chat in tempo reale all'applicazione. In questa guida introduttiva si userà Chat SDK per creare thread di chat che consentano agli utenti di avere conversazioni tra loro. Per altre informazioni sui concetti relativi alle chat, vedere la documentazione concettuale per le chat.

Prerequisiti

Configurazione

Aggiungere l'estensione

Aggiungere l'estensione Servizi di comunicazione di Azure per l'interfaccia della riga di comando di Azure usando il az extension comando .

az extension add --name communication

Accedere all'interfaccia della riga di comando di Azure

Sarà necessario accedere all'interfaccia della riga di comando di Azure. È possibile accedere eseguendo il az login comando dal terminale e specificando le credenziali.

(Facoltativo) Usare le operazioni di identità dell'interfaccia della riga di comando di Azure senza passare un endpoint o un token di accesso

Archiviare l'endpoint in una variabile di ambiente

È possibile configurare la variabile di ambiente per usare le operazioni di chat dell'interfaccia della AZURE_COMMUNICATION_ENDPOINT riga di comando di Azure senza dover usare --endpoint per passare l'endpoint. Per configurare una variabile di ambiente, aprire una finestra della console e selezionare il sistema operativo dalle schede seguenti. Sostituire <yourEndpoint> con l'endpoint effettivo.

Aprire una finestra della console e immettere il comando seguente:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

Dopo l'aggiunta della variabile di ambiente potrebbe essere necessario riavviare eventuali programmi in esecuzione che necessitano di leggere la variabile di ambiente, inclusa la finestra della console. Ad esempio, se si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Archiviare il token di accesso in una variabile di ambiente

È possibile configurare la variabile di ambiente per usare le operazioni di chat dell'interfaccia della AZURE_COMMUNICATION_ACCESS_TOKEN riga di comando di Azure senza dover usare --access-token per passare il token di accesso. Per configurare una variabile di ambiente, aprire una finestra della console e selezionare il sistema operativo dalle schede seguenti. Sostituire <yourAccessToken> con il token di accesso effettivo.

Aprire una finestra della console e immettere il comando seguente:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Dopo l'aggiunta della variabile di ambiente potrebbe essere necessario riavviare eventuali programmi in esecuzione che necessitano di leggere la variabile di ambiente, inclusa la finestra della console. Ad esempio, se si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Operazioni

Avviare un thread di chat

Usare il thread create comando per creare un thread di chat.

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

Se l'endpoint e il token di accesso sono stati archiviati nelle variabili di ambiente come indicato in precedenza, non sarà necessario passarli al comando.

az communication chat thread create --topic "<chatTopic>"
  • Usare <chatTopic> per assegnare al thread un argomento. È possibile aggiornare l'argomento dopo la creazione del thread di chat usando il thread update-topic comando .
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Aggiornare l'argomento di un thread di chat

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Sostituire <chatTopic> con il nuovo argomento della chat da impostare.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Elencare tutti i thread di chat

Il thread list comando restituisce l'elenco dei thread di chat di un utente.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Usare <startTime> facoltativamente per specificare il primo punto nel tempo per ottenere messaggi di chat.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Inviare un messaggio a un thread di chat

Usare il message send comando per inviare un messaggio a un thread di chat creato, identificato da threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Usare <content> per fornire il contenuto del messaggio di chat.
  • Usare <messageType> per specificare il tipo di contenuto del messaggio. I valori possibili sono text e html. Se non si specifica un valore, il valore predefinito è text.
  • Utilizzare <displayName> facoltativamente per specificare il nome visualizzato del mittente.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Elencare i messaggi di chat in un thread di chat

Il message list comando restituisce l'elenco dei messaggi di chat in un thread di chat.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Usare <startTime> facoltativamente per specificare il primo punto nel tempo per ottenere messaggi di chat.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Ricevere un messaggio di chat da un thread di chat

È possibile recuperare i messaggi di chat usando il message list comando .

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Sostituire <messageId> con l'ID del messaggio da recuperare.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Invia ricevuta di lettura

Usare il message receipt send comando per pubblicare un evento di ricezione di lettura in un thread, per conto di un utente.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Sostituire <messageId> per specificare l'ID del messaggio più recente letto dall'utente corrente.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Aggiungere un utente come partecipante al thread di chat

Quando si crea un thread di chat, è quindi possibile aggiungere e rimuovere utenti da esso. Aggiungendo utenti, è possibile concedere loro l'accesso per poter inviare messaggi al thread di chat e aggiungere o rimuovere altri partecipanti. Prima di chiamare il participant add comando, assicurarsi di aver acquisito un nuovo token di accesso e un'identità per tale utente.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Sostituire <userId> con userId.
  • Utilizzare <displayName> facoltativamente per specificare il nome visualizzato del mittente.
  • Usare <startTime> facoltativamente per specificare il primo punto nel tempo per ottenere messaggi di chat.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Elencare i partecipanti al thread in un thread di chat

Analogamente all'aggiunta di un partecipante, è anche possibile elencare i partecipanti da un thread.

Usare participant list il comando per recuperare i partecipanti del thread.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Usare <skip> facoltativamente per ignorare i partecipanti fino a una posizione specificata nella risposta.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Rimuovere un partecipante da un thread di chat

È possibile rimuovere un partecipante di chat da un thread di chat usando il comando "partecipante remove".

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Sostituire <chatThreadId> con l'ID del thread di chat.
  • Sostituire <userId> con l'id utente che si vuole rimuovere dal thread di chat.
  • Sostituire <endpoint> con l'endpoint Servizi di comunicazione di Azure.
  • Sostituire <token> con il token di accesso ottenuto in precedenza con il comando in esecuzione identity token issue .

Prerequisiti

Prima di iniziare, assicurarsi di:

  • Creare un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito.

  • Installare le versioni di Node.js Active LTS e Maintenance LTS.

  • Creare una risorsa di Servizi di comunicazione di Azure. Per informazioni dettagliate, vedere Creare una risorsa Servizi di comunicazione di Azure. Per questa guida introduttiva è necessario registrare l'endpoint della risorsa e stringa di connessione.

  • Creare tre Servizi di comunicazione di Azure Utenti e rilasciarli un token di accesso utente. Assicurarsi di impostare l'ambito per la chat e prendere nota della stringa del token e della stringa di user_id. La demo completa crea un thread con due partecipanti iniziali e quindi aggiunge un terzo partecipante al thread. È anche possibile usare l'interfaccia della riga di comando di Azure ed eseguire il comando seguente con il stringa di connessione per creare un utente e un token di accesso.

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

    Per informazioni dettagliate, vedere Usare l'interfaccia della riga di comando di Azure per creare e gestire i token di accesso.

Configurazione

Creare una nuova applicazione Web

Aprire prima di tutto il terminale o la finestra di comando per creare una nuova directory per l'app e passare a tale directory.

mkdir chat-quickstart && cd chat-quickstart

Eseguire npm init -y per creare un file package.json con le impostazioni predefinite.

npm init -y

Installare i pacchetti

Usare il npm install comando per installare gli SDK di Servizi di comunicazione seguenti per 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

L'opzione --save elenca la libreria come dipendenza nel file package.json.

Configurare il framework dell'app

Questo argomento di avvio rapido usa il pacchetto per aggregare gli asset dell'applicazione. Eseguire il comando seguente per installarlo ed elencarlo come dipendenza di sviluppo nel file package.json:

npm install parcel --save-dev

Creare un file index.html nella directory radice del progetto. Questo file verrà usato come modello per aggiungere funzionalità di chat usando Azure Communication Chat SDK per 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>

Nella directory radice del progetto creare un file denominato client.js in cui contenere la logica dell'applicazione per questa guida di avvio rapido.

Creare un client di chat

Per creare un client di chat nell'app Web, si useranno l'endpoint del servizio di comunicazione e il token di accesso generato come parte dei passaggi prerequisiti.

I token di accesso utente consentono di creare applicazioni client che eseguono l'autenticazione direttamente in Servizi di comunicazione di Azure. Questa guida introduttiva non illustra la creazione di un livello di servizio per gestire i token per l'applicazione di chat. Per altre informazioni sull'architettura della chat e sui token di accesso utente, vedere Concetti relativi alla chat per altre informazioni sui token di accesso.

All'interno di client.js usare l'endpoint e il token di accesso nel codice seguente per aggiungere funzionalità di chat usando Azure Communication Chat SDK per 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!');
  • Sostituire endpointUrl con l'endpoint della risorsa di Servizi di comunicazione, vedere Creare una risorsa Servizi di comunicazione di Azure se non è già stato fatto.
  • Sostituire userAccessToken con il token rilasciato.

Eseguire il codice

Eseguire il comando seguente per eseguire l'applicazione:

npx parcel index.html

Aprire il browser e passare a http://localhost:1234/. Nella console degli strumenti di sviluppo nel browser dovrebbe essere visualizzato quanto segue:

Azure Communication Chat client created!

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per JavaScript.

Nome Descrizione
ChatClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni sulla sottoscrizione e usarla per creare, ottenere, eliminare thread e sottoscrivere eventi di chat.
ChatThreadClient Questa classe è necessaria per la funzionalità di thread di chat. È possibile ottenere un'istanza tramite ChatClient e usarla per inviare/ricevere/aggiornare/eliminare messaggi, aggiungere/rimuovere/ottenere utenti, inviare notifiche di digitazione in corso e conferme di lettura.

Avviare un thread di chat

Usare il metodo createThread per creare un thread di chat.

createThreadRequest viene usato per descrivere la richiesta di thread:

  • Usare topic per dare un argomento a questa chat. Gli argomenti possono essere aggiornati dopo la creazione del thread di chat tramite la UpdateThread funzione .
  • Usare participants per elencare i partecipanti da aggiungere al thread di chat.

Quando viene risolto, createChatThread il metodo restituisce un oggetto CreateChatThreadResult. Questo modello contiene una chatThread proprietà in cui è possibile accedere al id del thread appena creato. È quindi possibile usare per ottenere un'istanza id di .ChatThreadClient Può ChatThreadClient quindi essere usato per eseguire operazioni all'interno del thread, ad esempio l'invio di messaggi o l'elenco dei partecipanti.

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

Quando si aggiorna la scheda del browser, nella console dovrebbe essere visualizzato quanto segue:

Thread created: <thread_id>

Ottenere un client di thread di chat

Il metodo getChatThreadClient restituisce un chatThreadClient per un thread già esistente. Può essere usato per eseguire operazioni sul thread creato: aggiungere partecipanti, inviare messaggi e così via. ThreadId è l'ID univoco del thread di chat esistente.

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

Aggiungere questo codice al posto del commento <CREATE CHAT THREAD CLIENT> in client.js, aggiornare la scheda del browser e controllare la console. Verrà visualizzato quanto segue:

Chat Thread client for threadId: <threadId>

Elencare tutti i thread di chat

Il listChatThreads metodo restituisce un PagedAsyncIterableIterator oggetto di tipo ChatThreadItem. Può essere usato per elencare tutti i thread di chat. Un iteratore di [ChatThreadItem] è la risposta restituita dai thread di elenco

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

Inviare un messaggio a un thread di chat

Usare il metodo sendMessage per inviare un messaggio a un thread identificato da threadId.

sendMessageRequest viene usato per descrivere la richiesta di messaggio:

  • Usare content per fornire il contenuto del messaggio di chat.

sendMessageOptions viene usato per descrivere i parametri facoltativi dell'operazione:

  • Usare senderDisplayName per specificare il nome visualizzato del mittente.
  • Usare type per specificare il tipo di messaggio, ad esempio 'text' o 'html';
  • Usare metadata facoltativamente per includere tutti gli altri dati da inviare insieme al messaggio. Questo campo fornisce agli sviluppatori un meccanismo per estendere la funzionalità dei messaggi di chat e aggiungere informazioni personalizzate per il caso d'uso. Ad esempio, quando si condivide un collegamento al file nel messaggio, è possibile aggiungere "hasAttachment: true" nei metadati in modo che l'applicazione del destinatario possa analizzare e visualizzare di conseguenza.

SendChatMessageResult è la risposta restituita dall'invio di un messaggio, contiene un ID, ovvero l'ID univoco del messaggio.

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

Aggiungere questo codice al posto del commento <SEND MESSAGE TO A CHAT THREAD> in client.js, aggiornare la scheda del browser e controllare la console.

Message sent!, message id:<number>

Ricevere messaggi di chat da un thread di chat

Con la segnalazione in tempo reale, è possibile sottoscrivere l'ascolto dei nuovi messaggi in arrivo e aggiornare i messaggi correnti in memoria di conseguenza. Servizi di comunicazione Azure supporta un elenco di eventi che è possibile sottoscrivere.

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

Aggiungere questo codice al posto del commento <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> in client.js. Aggiornare la scheda del browser. Nella console verrà visualizzato un messaggio Notification chatMessageReceived.

In alternativa, è possibile recuperare i messaggi di chat eseguendo il polling del metodo listMessages a intervalli specificati.


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

Aggiungere questo codice al posto del commento <LIST MESSAGES IN A CHAT THREAD> in client.js. Aggiornare la scheda, nella console si dovrebbe trovare l'elenco dei messaggi inviati in questo thread di chat.

listMessages restituisce tipi diversi di messaggi che possono essere identificati da chatMessage.type.

Per altri dettagli, vedere Tipi di messaggi.

Aggiungere un utente come partecipante al thread di chat

Dopo aver creato un thread di chat, è possibile aggiungere e rimuovere utenti. Aggiungendo utenti, è possibile concedere loro l'accesso per inviare messaggi al thread di chat e aggiungere/rimuovere altri partecipanti.

Prima di chiamare il addParticipants metodo, assicurarsi di aver acquisito un nuovo token di accesso e un'identità per tale utente. L'utente dovrà usare il token di accesso per inizializzare il client di chat.

addParticipantsRequest descrive l'oggetto richiesta in participants cui elenca i partecipanti da aggiungere al thread di chat;

  • id, obbligatorio, è l'identificatore di comunicazione da aggiungere al thread di chat.
  • displayName, facoltativo, è il nome visualizzato per il partecipante del thread.
  • shareHistoryTime, facoltativo, è l'ora da cui la cronologia delle chat viene condivisa con il partecipante. Per condividere la cronologia dall'inizio del thread di chat, impostare questa proprietà su qualsiasi data uguale o precedente all'ora di creazione del thread. Per condividere nessuna cronologia precedente all'aggiunta del partecipante, impostarla sulla data corrente. Per condividere una cronologia parziale, impostarla su una data a scelta.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Sostituire NEW_PARTICIPANT_Uedizione StandardR_ID con un nuovo ID utente Aggiungere questo codice al posto del <ADD NEW PARTICIPANT TO THREAD> commento in client.js

Elencare gli utenti in un thread di chat

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

Aggiungere questo codice al posto del commento <LIST PARTICIPANTS IN A THREAD> in client.js, aggiornare la scheda del browser e controllare la console. Verranno visualizzate informazioni sugli utenti in un thread.

Rimuovere un utente da un thread di chat

Analogamente all'aggiunta di un partecipante, è possibile rimuovere i partecipanti da un thread di chat. Per rimuovere, è necessario tenere traccia degli ID dei partecipanti aggiunti.

Usare il metodo removeParticipant in cui participant è l'utente di comunicazione da rimuovere dal thread.


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

Sostituire PARTICIPANT_ID con un ID utente usato nel passaggio precedente (<NEW_PARTICIPANT_Uedizione StandardR_ID>). Aggiungere questo codice al posto del commento <REMOVE PARTICIPANT FROM THREAD> in client.js.

Sottoscrivere lo stato di connessione delle notifiche in tempo reale

Sottoscrizione agli eventi realTimeNotificationConnected e realTimeNotificationDisconnected consente di sapere quando la connessione al server di chiamata è attiva.

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

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Prima di iniziare, assicurarsi di:

  • Creare un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito.

  • Installare Python 3.7+.

  • Creare una risorsa di Servizi di comunicazione di Azure. Per informazioni dettagliate, vedere Avvio rapido: Creare e gestire le risorse di Servizi di comunicazione. Per questa guida introduttiva è necessario registrare l'endpoint della risorsa e stringa di connessione.

  • Un token di accesso utente. Assicurarsi di impostare l'ambito per la chat e prendere nota della stringa del token e della stringa di user_id. È anche possibile usare l'interfaccia della riga di comando di Azure ed eseguire il comando seguente con il stringa di connessione per creare un utente e un token di accesso.

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

    Per informazioni dettagliate, vedere Usare l'interfaccia della riga di comando di Azure per creare e gestire i token di accesso.

Configurazione

Creare una nuova applicazione Python

Aprire il terminale o la finestra di comando, creare una nuova directory per l'app e passare a essa.

mkdir chat-quickstart && cd chat-quickstart

Usare un editor di testo per creare un file denominato start-chat.py nella directory radice del progetto. Aggiungere la struttura per il programma, inclusa la gestione delle eccezioni di base. Nelle sezioni seguenti si aggiungerà tutto il codice sorgente per questo argomento di avvio rapido a questo file.

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)

Installare SDK

Usare il comando seguente per installare l'SDK:


pip install azure-communication-chat

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per Python.

Nome Descrizione
ChatClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni sulla sottoscrizione e usarla per creare, ottenere ed eliminare thread.
ChatThreadClient Questa classe è necessaria per la funzionalità del thread di chat. È possibile ottenere un'istanza tramite ChatCliente usarla per inviare, ricevere, aggiornare ed eliminare messaggi. È anche possibile usarlo per aggiungere, rimuovere e ottenere gli utenti e inviare notifiche di digitazione e ricevute di lettura.

Creare un client di chat

Per creare un client di chat, usare l'endpoint di Servizi di comunicazione e il token di accesso generato come parte dei passaggi dei prerequisiti.

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

Questa guida introduttiva non illustra la creazione di un livello di servizio per gestire i token per l'applicazione di chat, ma è consigliabile. Per altre informazioni, vedere la sezione "Architettura chat" dei concetti di Chat.

Avviare un thread di chat

Usare il metodo create_chat_thread per creare un thread di chat.

  • Usare topic per assegnare al thread un argomento. È possibile aggiornare l'argomento dopo la creazione del thread di chat usando la update_thread funzione .
  • Usare thread_participants per elencare l'oggetto ChatParticipant da aggiungere al thread di chat. accetta ChatParticipant il CommunicationUserIdentifier tipo come user.

CreateChatThreadResult è il risultato restituito dalla creazione di un thread. È possibile usarlo per recuperare il id del thread di chat creato. Questa id operazione può quindi essere utilizzata per recuperare un ChatThreadClient oggetto usando il get_chat_thread_client metodo . È possibile usare ChatThreadClient per eseguire altre operazioni di chat a questo thread di chat.

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)

Ottenere un client di thread di chat

Il metodo get_chat_thread_client restituisce un client di thread per un thread già esistente. È possibile usarlo per eseguire operazioni sul thread creato. Ad esempio, è possibile aggiungere partecipanti e inviare messaggi. thread_id è l'ID univoco del thread di chat esistente.

È possibile usare ChatThreadClient per eseguire altre operazioni di chat a questo thread di chat.

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

Elencare tutti i thread di chat

Il list_chat_threads metodo restituisce un iteratore di tipo ChatThreadItem.

  • Usare start_time per specificare il primo punto nel tempo per ottenere i thread di chat.
  • Usare results_per_page per specificare il numero massimo di thread di chat restituiti per pagina.

Un iteratore di [ChatThreadItem] è la risposta restituita dai thread di elenco.

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)

Inviare un messaggio a un thread di chat

Usare il send_message metodo per inviare un messaggio a un thread di chat appena creato, identificato da thread_id.

  • Usare content per fornire il contenuto del messaggio di chat.
  • Usare chat_message_type per specificare il tipo di contenuto del messaggio. I valori possibili sono text e html. Se non si specifica un valore, il valore predefinito è text.
  • Usare sender_display_name per specificare il nome visualizzato del mittente.
  • Usare metadata facoltativamente per includere eventuali dati aggiuntivi da inviare insieme al messaggio. Questo campo fornisce agli sviluppatori un meccanismo per estendere la funzionalità dei messaggi di chat e aggiungere informazioni personalizzate per il caso d'uso. Ad esempio, quando si condivide un collegamento al file nel messaggio, è possibile aggiungere "hasAttachment:true" nei metadati in modo che l'applicazione del destinatario possa analizzare e visualizzare di conseguenza.

SendChatMessageResult è la risposta restituita dall'invio di un messaggio. Contiene un ID, ovvero l'ID univoco del messaggio.

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)

Ricevere messaggi di chat da un thread di chat

È possibile recuperare i messaggi di chat eseguendo il polling del metodo list_messages a intervalli specificati.

  • Utilizzare results_per_page per specificare il numero massimo di messaggi da restituire per pagina.
  • Usare start_time per specificare il momento più recente per ottenere i messaggi.

Un iteratore di è la risposta restituita dall'elenco dei [ChatMessage] messaggi.

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 restituisce la versione più recente del messaggio, incluse le modifiche o le eliminazioni apportate al messaggio utilizzando update_message e delete_message. Per i messaggi eliminati, ChatMessage.deleted_on restituisce un datetime valore che indica quando il messaggio è stato eliminato. Per i messaggi modificati, ChatMessage.edited_on restituisce un datetime valore che indica quando il messaggio è stato modificato. È possibile accedere all'ora originale di creazione del messaggio usando ChatMessage.created_on, che può essere usato per ordinare i messaggi.

list_messages restituisce tipi diversi di messaggi, che possono essere identificati da ChatMessage.type.

Per altre informazioni, vedere Tipi di messaggio.

Invia ricevuta di lettura

Usare il send_read_receipt metodo per pubblicare un evento di ricezione di lettura in un thread, per conto di un utente.

  • Usare message_id per specificare l'ID del messaggio più recente letto dall'utente corrente.
content='hello world'

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

Aggiungere un utente come partecipante al thread di chat

Quando si crea un thread di chat, è quindi possibile aggiungere e rimuovere utenti da esso. Aggiungendo utenti, è possibile concedere loro l'accesso per poter inviare messaggi al thread di chat e aggiungere o rimuovere altri partecipanti. Prima di chiamare il add_participants metodo, assicurarsi di aver acquisito un nuovo token di accesso e un'identità per tale utente. L'utente deve disporre di tale token di accesso per inizializzare il client di chat.

È possibile aggiungere uno o più utenti al thread di chat usando il add_participants metodo , purché sia disponibile un nuovo token di accesso e un'identità per tutti gli utenti.

Viene restituito un list(tuple(ChatParticipant, CommunicationError)). Quando il partecipante viene aggiunto correttamente, è previsto un elenco vuoto. Se si verifica un errore durante l'aggiunta di un partecipante, l'elenco viene popolato con i partecipanti non riusciti, insieme all'errore rilevato.

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)

Elencare i partecipanti al thread in un thread di chat

Analogamente all'aggiunta di un partecipante, è anche possibile elencare i partecipanti da un thread.

Usare list_participants per recuperare i partecipanti del thread. Entrambi i comandi seguenti sono facoltativi:

  • Utilizzare results_per_page per specificare il numero massimo di partecipanti da restituire per pagina.
  • Usare skip per ignorare i partecipanti fino a una posizione specificata nella risposta.

Un iteratore di [ChatParticipant] è la risposta restituita dall'elenco dei partecipanti.

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)

Eseguire il codice

Eseguire l'applicazione dalla directory dell'applicazione con il comando python.

python start-chat.py

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Configurazione

Creare una nuova applicazione Java

Aprire la finestra del terminale o di comando e passare alla directory in cui creare l'applicazione Java. Eseguire il comando seguente per generare il progetto Java dal modello maven-archetype-quickstart.

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

Si noterà che l'obiettivo 'generate' ha creato una directory con lo stesso nome di artifactId. In questa directory, src/main/java directory contiene il codice sorgente del progetto, la directory src/test/java contiene l'origine di test e il file pom.xml è il modello a oggetti del progetto o POM.

Aggiornare il file POM dell'applicazione per usare Java 8 o versione successiva:

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

Aggiungere i riferimenti al pacchetto per Chat SDK

Nel file POM fare riferimento al pacchetto azure-communication-chat con le API di chat:

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

Per l'autenticazione, il client deve fare riferimento al pacchetto azure-communication-common:

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

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per Java.

Nome Descrizione
ChatClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni della sottoscrizione e usarla per creare, ottenere ed eliminare thread.
ChatAsyncClient Questa classe è necessaria per la funzionalità di chat asincrona. È possibile crearne un'istanza con le informazioni della sottoscrizione e usarla per creare, ottenere ed eliminare thread.
ChatThreadClient Questa classe è necessaria per la funzionalità di thread di chat. È possibile ottenere un'istanza tramite ChatClient e usarla per inviare/ricevere/aggiornare/eliminare messaggi, aggiungere/rimuovere/ottenere utenti, inviare notifiche di digitazione in corso e conferme di lettura.
ChatThreadAsyncClient Questa classe è necessaria per la funzionalità di thread di chat asincrona. È possibile ottenere un'istanza tramite ChatAsyncClient e usarla per inviare/ricevere/aggiornare/eliminare messaggi, aggiungere/rimuovere/ottenere utenti, inviare notifiche di digitazione in corso e conferme di lettura.

Creare un client di chat

Per creare un client di chat, si useranno l''endpoint di Servizi di comunicazione e il token di accesso generato nell'ambito dei passaggi preliminari. I token di accesso utente consentono di creare applicazioni client che eseguono l'autenticazione direttamente in Servizi di comunicazione di Azure. Dopo aver generato questi token nel server, passarli a un dispositivo client. È necessario usare la classe CommunicationTokenCredential di Common SDK per passare il token al client di chat.

Altre informazioni sull'architettura di chat

Quando si aggiungono le istruzioni di importazione, assicurarsi di aggiungere solo le importazioni dagli spazi dei nomi com.azure.communication.chat e com.azure.communication.chat.models e non dallo spazio dei nomi com.azure.communication.chat.implementation. Nel file App.java generato tramite Maven, è possibile usare il codice seguente per iniziare:

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

Avviare un thread di chat

Usare il metodo createChatThread per creare un thread di chat. createChatThreadOptions viene usato per descrivere la richiesta di thread.

  • Usare il topic parametro del costruttore per assegnare un argomento a questa chat; L'argomento può essere aggiornato dopo la creazione del thread di chat tramite la UpdateThread funzione .
  • Usare participants per elencare i partecipanti al thread da aggiungere al thread. ChatParticipant accetta l'utente creato nella guida di avvio rapido Token di accesso utente.

CreateChatThreadResult è la risposta restituita dalla creazione di un thread di chat. Contiene un getChatThread() metodo, che restituisce l'oggetto ChatThread che può essere usato per ottenere il client thread da cui è possibile ottenere ChatThreadClient per eseguire operazioni sul thread creato: aggiungere partecipanti, inviare messaggi e così via. L'oggetto ChatThread contiene anche il getId() metodo , che recupera l'ID univoco del thread.

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

Elencare i thread di chat

Usare il listChatThreads metodo per recuperare un elenco di thread di chat esistenti.

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

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

Ottenere un client di thread di chat

Il metodo getChatThreadClient restituisce un client di thread per un thread già esistente. Può essere usato per eseguire operazioni sul thread creato: aggiungere partecipanti, inviare messaggi e così via. chatThreadId è l'ID univoco del thread di chat esistente.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Inviare un messaggio a un thread di chat

Usare il sendMessage metodo per inviare un messaggio al thread creato, identificato da chatThreadId. sendChatMessageOptions consente di descrivere la richiesta del messaggio di chat.

  • Usare content per fornire il contenuto del messaggio di chat.
  • Usare type per specificare il tipo di contenuto del messaggio di chat, TEXT o HTML.
  • Usare senderDisplayName per specificare il nome visualizzato del mittente.
  • Usare metadata facoltativamente per includere eventuali dati aggiuntivi da inviare insieme al messaggio. Questo campo fornisce agli sviluppatori un meccanismo per estendere la funzionalità dei messaggi di chat e aggiungere informazioni personalizzate per il caso d'uso. Ad esempio, quando si condivide un collegamento al file nel messaggio, è possibile aggiungere hasAttachment:true metadati in modo che l'applicazione del destinatario possa analizzare e visualizzare di conseguenza.

Il sendChatMessageResult di risposta contiene un id, ovvero l'ID univoco del messaggio.

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

Ricevere messaggi di chat da un thread di chat

È possibile recuperare i messaggi di chat eseguendo il polling del metodo listMessages sul client del thread di chat a intervalli specificati.

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

listMessages restituisce la versione più recente del messaggio, incluse eventuali modifiche o eliminazioni che si sono verificate nel messaggio usando .editMessage() e .deleteMessage(). Per i messaggi eliminati, chatMessage.getDeletedOn() restituisce un valore datetime che indica quando il messaggio è stato eliminato. Per i messaggi modificati, chatMessage.getEditedOn() restituisce un valore datetime che indica quando il messaggio è stato modificato. È possibile accedere all'ora originale di creazione del messaggio usando chatMessage.getCreatedOn() e tale ora può essere usata per ordinare i messaggi.

Altre informazioni sui tipi di messaggio sono disponibili qui: Tipi di messaggi.

Invia ricevuta di lettura

Usare il sendReadReceipt metodo per pubblicare un evento di ricezione di lettura in un thread di chat per conto di un utente. chatMessageId è l'ID univoco del messaggio di chat letto.

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

Elencare i partecipanti alla chat

Usare listParticipants per recuperare una raccolta di pagine contenente i partecipanti del thread di chat identificato da chatThreadId.

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

Aggiungere un utente come partecipante al thread di chat

Dopo aver creato un thread di chat, è possibile aggiungere e rimuovere utenti. Aggiungendo utenti, è possibile concedere loro l'accesso per inviare messaggi al thread di chat e aggiungere/rimuovere altri partecipanti. Per iniziare, sarà necessario ottenere un nuovo token di accesso e un'identità per tale utente. Prima di chiamare il metodo addParticipants, assicurarsi di aver acquisito un nuovo token di accesso e un'identità per tale utente. L'utente dovrà usare il token di accesso per inizializzare il client di chat.

Usare il addParticipants metodo per aggiungere partecipanti al thread.

  • communicationIdentifier, obbligatorio, è CommunicationIdentifier creato da CommunicationIdentityClient nell'argomento di avvio rapido Token di accesso utente.
  • displayName, facoltativo, è il nome visualizzato per il partecipante del thread.
  • shareHistoryTime, facoltativo, è l'ora da cui la cronologia delle chat viene condivisa con il partecipante. Per condividere la cronologia dall'inizio del thread di chat, impostare questa proprietà su qualsiasi data uguale o precedente all'ora di creazione del thread. Per condividere nessuna cronologia precedente all'aggiunta del partecipante, impostarla sulla data corrente. Per condividere una cronologia parziale, impostarla sulla data richiesta.
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);

Eseguire il codice

Passare alla directory contenente il file pom.xml e compilare il progetto tramite il comando mvn seguente.

mvn compile

Compilare il pacchetto.

mvn package

Eseguire il comando mvn seguente per eseguire l'app.

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

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Prima di iniziare, assicurarsi di:

  • Creare un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito.

  • Installare Android Studio, verrà usato Android Studio per creare un'applicazione Android per l'avvio rapido per installare le dipendenze.

  • Creare una risorsa di Servizi di comunicazione di Azure. Per informazioni dettagliate, vedere Creare una risorsa Servizi di comunicazione di Azure. Per questa guida introduttiva è necessario registrare l'endpoint della risorsa e stringa di connessione.

  • Creare due utenti di Servizi di comunicazione e rilasciarli un token di accesso utente. Assicurarsi di impostare l'ambito per la chat e prendere nota della stringa del token e della stringa user_id. In questo argomento di avvio rapido si creerà un thread con un partecipante iniziale e quindi si aggiungerà un secondo partecipante al thread. È anche possibile usare l'interfaccia della riga di comando di Azure ed eseguire il comando seguente con il stringa di connessione per creare un utente e un token di accesso.

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

    Per informazioni dettagliate, vedere Usare l'interfaccia della riga di comando di Azure per creare e gestire i token di accesso.

Configurazione

Creare una nuova applicazione Android

  1. Aprire Android Studio e selezionare Create a new project.
  2. Nella finestra successiva selezionare Empty Activity come modello di progetto.
  3. Quando si scelgono le opzioni, immettere ChatQuickstart come nome del progetto.
  4. Fare clic su Avanti e scegliere la directory in cui si vuole creare il progetto.

Installare le librerie

Si userà Gradle per installare le dipendenze di Servizi di comunicazione necessarie. Dalla riga di comando passare all'interno della directory radice del ChatQuickstart progetto. Aprire il file build.gradle dell'app e aggiungere le dipendenze seguenti alla ChatQuickstart destinazione:

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

Fare riferimento a https://search.maven.org/artifact/com.azure.android/azure-communication-common e https://search.maven.org/artifact/com.azure.android/azure-communication-chat per i numeri di versione più recenti.

Escludere i meta file nelle opzioni di creazione pacchetti nella radice 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")
    }
}

(Alternativa) Per installare librerie tramite Maven

Per importare la libreria nel progetto usando il sistema di compilazione Maven , aggiungerla alla dependencies sezione del file dell'app pom.xml , specificandone l'ID artefatto e la versione da usare:

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

Configurare la funzione di Azure

Per informazioni dettagliate, vedere Integrazione delle funzioni di Azure. È consigliabile eseguire l'integrazione con Funzioni di Azure per evitare parametri dell'applicazione hardcoded.

Configurare le costanti dell'applicazione:

Creare una classe ApplicationConstants che archivia tutte le costanti dell'applicazione:

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

Configurare i segnaposto

Aprire e modificare il file MainActivity.java. In questa guida introduttiva si aggiungerà il codice a MainActivitye si visualizzerà l'output nella console. Questa guida introduttiva non risolve la compilazione di un'interfaccia utente. Nella parte superiore del file importare , Azure Communication CommonAzure Communication Chate altre librerie di sistema:

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;

Copiare il codice seguente nella classe MainActivity nel file 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());
        }
    }

Inizializzare i parametri dell'applicazione

Nota

L'inizializzazione ApplicationConstants deve essere aggiunta a MainActivity.java se viene soddisfatta una delle condizioni seguenti: 1. La funzionalità di notifica push non è abilitata. 2. La versione per la libreria chat di comunicazione di Azure per Android è < "2.0.0". In caso contrario, fare riferimento al passaggio 11 nelle notifiche push android. Per informazioni di riferimento, vedere l'app di esempio della versione dell'SDK che si sta usando.

ACS_ENDPOINTFIRST_USER_ACCESS_TOKEN e FIRST_USER_ID vengono restituiti dalla chiamata di Funzione di Azure. Per informazioni dettagliate, vedere Integrazione delle funzioni di Azure. Viene usata la risposta dalla chiamata a Funzione di Azure per inizializzare l'elenco di parametri:

  • ACS_ENDPOINT: l'endpoint della risorsa di Servizi di comunicazione.
  • FIRST_USER_ID e SECOND_USER_ID: ID utente di Servizi di comunicazione validi generati dalla risorsa di Servizi di comunicazione.
  • FIRST_USER_ACCESS_TOKEN: token di accesso di Servizi di comunicazione per <FIRST_USER_ID>.

Blocco di codice per l'inizializzazione dei parametri dell'applicazione chiamando funzione di Azure:

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

Creare un client di chat

Sostituire il commento <CREATE A CHAT CLIENT> con il codice seguente (inserire le istruzioni import all'inizio del file):

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

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per JavaScript.

Nome Descrizione
ChatClient/ChatAsyncClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni sulla sottoscrizione e usarla per creare, ottenere, eliminare thread e sottoscrivere eventi di chat.
ChatThreadClient/ChatThreadAsyncClient Questa classe è necessaria per la funzionalità di thread di chat. È possibile ottenere un'istanza tramite ChatClient e usarla per inviare/ricevere/aggiornare/eliminare messaggi, aggiungere/rimuovere/ottenere utenti, inviare notifiche di digitazione in corso e conferme di lettura.

Avviare un thread di chat

Verrà usato ChatAsyncClient per creare un nuovo thread con un utente iniziale.

Sostituire il commento <CREATE A CHAT THREAD> con il codice seguente:

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

Ottenere un client di thread di chat

Ora che è stato creato un thread di chat, si otterrà un oggetto ChatThreadAsyncClient per eseguire operazioni all'interno del thread. Sostituire il commento <CREATE A CHAT THREAD CLIENT> con il codice seguente:

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

Inviare un messaggio a un thread di chat

A questo thread verrà inviato un messaggio.

Sostituire il commento <SEND A MESSAGE> con il codice seguente:

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

Ricevere messaggi di chat da un thread di chat

Notifiche in tempo reale

Con la segnalazione in tempo reale, è possibile sottoscrivere nuovi messaggi in arrivo e aggiornare i messaggi correnti in memoria di conseguenza. Servizi di comunicazione Azure supporta un elenco di eventi che è possibile sottoscrivere.

Sostituire il commento <RECEIVE CHAT MESSAGES> con il codice seguente (inserire le istruzioni import all'inizio del file):


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

Importante

Problema noto: quando si usa Android Chat e Calling SDK insieme nella stessa applicazione, la funzionalità di notifiche in tempo reale di Chat SDK non funziona. È possibile che si verifichi un problema di risoluzione delle dipendenze. Mentre si sta lavorando a una soluzione, è possibile disattivare la funzionalità delle notifiche in tempo reale aggiungendo le informazioni di dipendenza seguenti nel file build.gradle dell'app ed eseguire invece il polling dell'API GetMessages per visualizzare i messaggi in arrivo agli utenti.

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'

Si noti che con l'aggiornamento precedente, se l'applicazione tenta di toccare un'API di notifica come chatAsyncClient.startRealtimeNotifications() o chatAsyncClient.addEventHandler(), si verifica un errore di runtime.

Notifiche push

Per informazioni dettagliate, vedere Notifiche push Android.

Aggiungere un utente come partecipante al thread di chat

Sostituire il commento <ADD A USER> con il codice seguente:

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

Elencare gli utenti in un thread

Sostituire il <LIST USERS> commento con il codice seguente (inserire le istruzioni import all'inizio del file):

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

Rimuovere un utente da un thread di chat

Ora verrà rimosso il secondo utente dal thread.

Sostituire il commento <REMOVE A USER> con il codice seguente:

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

Inviare una notifica di digitazione

Sostituire il commento <SEND A TYPING NOTIFICATION> con il codice seguente:

chatThreadAsyncClient.sendTypingNotification().get();

Inviare una ricevuta di lettura

Verrà inviata la ricevuta di lettura per il messaggio inviato in precedenza.

Sostituire il commento <SEND A READ RECEIPT> con il codice seguente:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Elencare le ricevute di lettura

Sostituire il commento <READ RECEIPTS> con il codice seguente:

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

Eseguire il codice

In Android Studio premere il pulsante Esegui per compilare ed eseguire il progetto. Nella console è possibile visualizzare l'output dal codice e dall'output del logger da ChatClient.

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Prima di iniziare, assicurarsi di:

  • Creare un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito.

  • Installare Visual Studio

  • Creare una risorsa di Servizi di comunicazione di Azure. Per informazioni dettagliate, vedere Creare una risorsa Servizi di comunicazione di Azure. Per questa guida introduttiva è necessario registrare l'endpoint della risorsa e stringa di connessione.

  • Un token di accesso utente. Assicurarsi di impostare l'ambito per la chat e prendere nota della stringa del token e della stringa di user_id. È anche possibile usare l'interfaccia della riga di comando di Azure ed eseguire il comando seguente con il stringa di connessione per creare un utente e un token di accesso.

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

    Per informazioni dettagliate, vedere Usare l'interfaccia della riga di comando di Azure per creare e gestire i token di accesso.

Configurazione

Creare una nuova applicazione C#

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome ChatQuickstart. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.

dotnet new console -o ChatQuickstart

Passare alla cartella dell'app appena creata e usare il comando dotnet build per compilare l'applicazione.

cd ChatQuickstart
dotnet build

Installare il pacchetto

Installare Azure Communication Chat SDK per .NET

dotnet add package Azure.Communication.Chat

Modello a oggetti

Le classi seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per C#.

Nome Descrizione
ChatClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni della sottoscrizione e usarla per creare, ottenere ed eliminare thread.
ChatThreadClient Questa classe è necessaria per la funzionalità di thread di chat. Si ottiene un'istanza tramite ChatClient e la si usa per inviare/ricevere/aggiornare/eliminare messaggi, aggiungere/rimuovere/ottenere partecipanti, inviare notifiche di digitazione e ricevute di lettura.

Creare un client di chat

Per creare un client di chat, si userà l'endpoint di Servizi di comunicazione e il token di accesso generato come parte dei passaggi dei prerequisiti. È necessario usare la CommunicationIdentityClient classe di Identity SDK per creare un utente e rilasciare un token da passare al client di chat.

Vedere altre informazioni sui token di accesso utente.

Questa guida introduttiva non illustra la creazione di un livello di servizio per gestire i token per l'applicazione di chat, anche se è consigliabile. Altre informazioni sull'architettura di chat

Copiare i frammenti di codice seguenti e incollarli nel file di origine: 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);
        }
    }
}

Avviare un thread di chat

Usare il createChatThread metodo in chatClient per creare un thread di chat

  • Usare topic per specificare un argomento per questa chat. L'argomento può essere aggiornato dopo la creazione del thread di chat usando la funzione UpdateTopic.
  • Usare la proprietà participants per passare un elenco di oggetti ChatParticipant da aggiungere al thread di chat. L'oggetto ChatParticipant viene inizializzato con un oggetto CommunicationIdentifier. CommunicationIdentifier può essere di tipo CommunicationUserIdentifiero MicrosoftTeamsUserIdentifierPhoneNumberIdentifier. Ad esempio, per ottenere un CommunicationIdentifier oggetto, è necessario passare un ID di accesso creato seguendo le istruzioni riportate di seguito per Creare un utente

L'oggetto risposta del createChatThread metodo contiene i chatThread dettagli. Per interagire con le operazioni del thread di chat, ad esempio l'aggiunta di partecipanti, l'invio di un messaggio, l'eliminazione di un messaggio e così via, è necessario creare un'istanza chatThreadClient del client usando il GetChatThreadClient metodo nel ChatClient client.

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;

Ottenere un client di thread di chat

Il metodo GetChatThreadClient restituisce un client di thread per un thread già esistente. Può essere usato per eseguire operazioni sul thread creato: aggiungere membri, inviare messaggi e così via. threadId è l'ID univoco del thread di chat esistente.

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

Elencare tutti i thread di chat

Usare GetChatThreads per recuperare tutti i thread di chat di cui fa parte l'utente.

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

Inviare un messaggio a un thread di chat

Usare SendMessage per inviare un messaggio a un thread.

  • Usare content per fornire il contenuto per il messaggio, è obbligatorio.
  • Usare type per il tipo di contenuto del messaggio, ad esempio 'Text' o 'Html'. Se non specificato, verrà impostato 'Text'.
  • Usare senderDisplayName per specificare il nome visualizzato del mittente. Se non specificato, verrà impostata una stringa vuota.
  • Usare metadata facoltativamente per includere eventuali dati aggiuntivi da inviare insieme al messaggio. Questo campo fornisce agli sviluppatori un meccanismo per estendere la funzionalità dei messaggi di chat e aggiungere informazioni personalizzate per il caso d'uso. Ad esempio, quando si condivide un collegamento al file nel messaggio, è possibile aggiungere "hasAttachment:true" nei metadati in modo che l'applicazione del destinatario possa analizzare e visualizzare di conseguenza.
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;

Ricevere messaggi di chat da un thread di chat

È possibile recuperare i messaggi di chat eseguendo il polling del metodo GetMessages sul client del thread di chat a intervalli specificati.

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

GetMessages accetta il parametro facoltativo DateTimeOffset. Se tale offset viene specificato, si riceveranno messaggi ricevuti, aggiornati o eliminati dopo di esso. Si noti che verranno restituiti anche i messaggi ricevuti prima della data/ora di offset ma modificati o rimossi dopo tale data/ora.

GetMessages restituisce la versione più recente del messaggio, incluse eventuali modifiche o eliminazioni che si sono verificate nel messaggio usando UpdateMessage e DeleteMessage. Per i messaggi eliminati, chatMessage.DeletedOn restituisce un valore datetime che indica quando il messaggio è stato eliminato. Per i messaggi modificati, chatMessage.EditedOn restituisce un valore datetime che indica quando il messaggio è stato modificato. È possibile accedere all'ora originale di creazione del messaggio usando chatMessage.CreatedOn e tale ora può essere usata per ordinare i messaggi.

GetMessages restituisce tipi diversi di messaggi che possono essere identificati da chatMessage.Type. Questi tipi sono:

  • Text: messaggio di chat normale inviato da un membro del thread.

  • Html: messaggio di testo formattato. Tenere presente che attualmente gli utenti di Servizi di comunicazione non possono inviare messaggi in formato RTF. Questo tipo di messaggio è supportato per i messaggi inviati da utenti di Teams a utenti di Servizi di comunicazione in scenari di interoperabilità di Teams.

  • TopicUpdated: messaggio di sistema che indica che l'argomento è stato aggiornato. (sola lettura)

  • ParticipantAdded: messaggio di sistema che indica che uno o più partecipanti sono stati aggiunti al thread di chat. (sola lettura)

  • ParticipantRemoved: messaggio di sistema che indica che un partecipante è stato rimosso dal thread di chat.

Per altri dettagli, vedere Tipi di messaggi.

Aggiungere un utente come partecipante al thread di chat

Dopo aver creato un thread, è possibile aggiungere e rimuovere utenti. Aggiungendo utenti, è possibile concedere loro l'accesso per poter inviare messaggi al thread e aggiungere/rimuovere altri partecipanti. Prima di chiamare AddParticipants, verificare di avere acquisito un nuovo token di accesso e un'identità per tale utente. L'utente dovrà usare il token di accesso per inizializzare il client di chat.

Usare AddParticipants per aggiungere uno o più partecipanti al thread di chat. Di seguito sono riportati gli attributi supportati per ogni partecipante del thread:

  • communicationUser, obbligatorio, è l'identità del partecipante del thread.
  • displayName, facoltativo, è il nome visualizzato per il partecipante del thread.
  • shareHistoryTime, facoltativo, ora da cui la cronologia delle chat viene condivisa con il partecipante.
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);

Ottenere i partecipanti al thread

Usare GetParticipants per recuperare i partecipanti del thread di chat.

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

Invia ricevuta di lettura

Usare SendReadReceipt per notificare ad altri partecipanti che il messaggio viene letto dall'utente.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Eseguire il codice

Eseguire l'applicazione dalla directory dell'applicazione con il comando dotnet run.

dotnet run

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Prima di iniziare, assicurarsi di:

  • Creare un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito.

  • Installare Xcode e CocoaPods. Usare Xcode per creare un'applicazione iOS per la guida introduttiva e CocoaPods per installare le dipendenze.

  • Creare una risorsa di Servizi di comunicazione di Azure. Per informazioni dettagliate, vedere Avvio rapido: Creare e gestire le risorse di Servizi di comunicazione. Per questa guida introduttiva è necessario registrare l'endpoint della risorsa e stringa di connessione.

  • Creare due utenti in Servizi di comunicazione di Azure e rilasciarli un token di accesso utente. Assicurarsi di impostare l'ambito per la chat e prendere nota della stringa del token e della stringa di user_id. In questa guida introduttiva si crea un thread con un partecipante iniziale e quindi si aggiunge un secondo partecipante al thread. È anche possibile usare l'interfaccia della riga di comando di Azure ed eseguire il comando seguente con il stringa di connessione per creare un utente e un token di accesso.

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

    Per informazioni dettagliate, vedere Usare l'interfaccia della riga di comando di Azure per creare e gestire i token di accesso.

Configurazione

Creare una nuova applicazione iOS

Aprire Xcode e selezionare Create a new Xcode project. Selezionare quindi iOS come piattaforma e app per il modello.

Per il nome del progetto immettere ChatQuickstart. Selezionare quindi Storyboard come interfaccia, UIKit App Delegate come ciclo di vita e Swift come linguaggio.

Selezionare Avanti e scegliere la directory in cui si vuole creare il progetto.

Installare le librerie

Usare CocoaPods per installare le dipendenze di Servizi di comunicazione necessarie.

Dalla riga di comando passare alla directory radice del ChatQuickstart progetto iOS. Creare un podfile con il comando seguente: pod init.

Aprire podfile e aggiungere le dipendenze seguenti alla ChatQuickstart destinazione:

pod 'AzureCommunicationChat', '~> 1.3.4'

Installare le dipendenze con il comando seguente: pod install. Si noti che viene creata anche un'area di lavoro Xcode.

Dopo aver eseguito pod install, riaprire il progetto in Xcode selezionando l'oggetto appena creato .xcworkspace.

Configurare i segnaposto

Aprire l'area di lavoro ChatQuickstart.xcworkspace in Xcode e quindi aprire ViewController.swift.

In questa guida introduttiva si aggiunge il codice a viewControllere si visualizza l'output nella console Xcode. Questa guida introduttiva non risolve la compilazione di un'interfaccia utente in iOS.

Nella parte superiore di viewController.swiftimportare le AzureCommunication librerie e AzureCommunicatonChat :

import AzureCommunicationCommon
import AzureCommunicationChat

Copiare il codice seguente nel viewDidLoad() metodo di 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)")
            }
        }
    }

A scopo dimostrativo, si userà un semaforo per sincronizzare il codice. Nei passaggi seguenti sostituire i segnaposto con il codice di esempio usando la libreria Servizi di comunicazione di Azure Chat.

Creare un client di chat

Per creare un client di chat, si userà l'endpoint di Servizi di comunicazione e il token di accesso generato come parte dei passaggi dei prerequisiti.

Vedere altre informazioni sui token di accesso utente.

Questa guida introduttiva non illustra la creazione di un livello di servizio per gestire i token per l'applicazione di chat, anche se è consigliabile. Altre informazioni sull'architettura di chat

Sostituire il commento con il frammento <CREATE A CHAT CLIENT> di codice seguente:

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
)

Sostituire <ACS_RESOURCE_ENDPOINT> con l'endpoint della risorsa Servizi di comunicazione di Azure. Sostituire <ACCESS_TOKEN> con un token di accesso valido di Servizi di comunicazione.

Modello a oggetti

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Chat SDK per iOS.

Nome Descrizione
ChatClient Questa classe è necessaria per la funzionalità di chat. È possibile crearne un'istanza con le informazioni sulla sottoscrizione e usarla per creare, ottenere, eliminare thread e sottoscrivere eventi di chat.
ChatThreadClient Questa classe è necessaria per la funzionalità del thread di chat. È possibile ottenere un'istanza tramite ChatCliente usarla per inviare, ricevere, aggiornare ed eliminare messaggi. È anche possibile usarlo per aggiungere, rimuovere e ottenere utenti, inviare notifiche di digitazione e ricevute di lettura.

Avviare un thread di chat

CreateChatThreadResult è la risposta restituita dalla creazione di un thread di chat. Contiene una chatThread proprietà che è l'oggetto ChatThreadProperties . Questo oggetto contiene il threadId che può essere usato per ottenere un ChatThreadClient oggetto per l'esecuzione di operazioni sul thread creato: aggiungere partecipanti, inviare messaggi e così via.

Sostituire il commento con il frammento <CREATE A CHAT THREAD> di codice seguente:

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

Sostituire <USER_ID> con un ID utente di Servizi di comunicazione valido.

Si sta usando un semaforo qui per attendere il gestore di completamento prima di continuare. Nei passaggi successivi si userà dalla threadId risposta restituita al gestore di completamento.

Elencare tutti i thread di chat

Dopo aver creato un thread di chat, è possibile elencare tutti i thread di chat chiamando il listChatThreads metodo su ChatClient. Sostituire il commento <LIST ALL CHAT THREADS> con il codice seguente:

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

Ottenere un client di thread di chat

Il metodo createClient restituisce un ChatThreadClient per un thread già esistente. Può essere usato per eseguire operazioni sul thread creato: aggiungere partecipanti, inviare messaggi e così via. ThreadId è l'ID univoco del thread di chat esistente.

Sostituire il commento <GET A CHAT THREAD CLIENT> con il codice seguente:

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

Inviare un messaggio a un thread di chat

Usare il send metodo per inviare un messaggio a un thread identificato da threadId.

SendChatMessageRequest viene usato per descrivere la richiesta di messaggio:

  • Usare content per fornire il contenuto del messaggio di chat
  • Utilizzare senderDisplayName per specificare il nome visualizzato del mittente
  • Usare type per specificare il tipo di messaggio, ad esempio 'text' o 'html'
  • Usare metadata facoltativamente per includere eventuali dati aggiuntivi da inviare insieme al messaggio. Questo campo fornisce agli sviluppatori un meccanismo per estendere la funzionalità dei messaggi di chat e aggiungere informazioni personalizzate per il caso d'uso. Ad esempio, quando si condivide un collegamento al file nel messaggio, è possibile aggiungere "hasAttachment:true" nei metadati in modo che l'applicazione del destinatario possa analizzare e visualizzare di conseguenza.

SendChatMessageResult è la risposta restituita dall'invio di un messaggio, contiene un ID, ovvero l'ID univoco del messaggio.

Sostituire il commento con il frammento <SEND A MESSAGE> di codice seguente:

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

Inviare una ricevuta di lettura

Usare il sendReadReceipt metodo per pubblicare un evento di ricezione di lettura in un thread di chat per conto di un utente. messageId è l'ID univoco del messaggio di chat letto.

Sostituire il commento <SEND A READ RECEIPT> con il codice seguente:

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

Ricevere messaggi di chat da un thread di chat

Con la segnalazione in tempo reale, è possibile sottoscrivere l'ascolto dei nuovi messaggi in arrivo e aggiornare i messaggi correnti in memoria di conseguenza. Servizi di comunicazione Azure supporta un elenco di eventi che è possibile sottoscrivere.

Sostituire il commento <RECEIVE MESSAGES> con il codice seguente. Dopo aver abilitato le notifiche, provare a inviare nuovi messaggi per visualizzare 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
    }
})

In alternativa, è possibile recuperare i messaggi di chat eseguendo il polling del metodo listMessages a intervalli specificati. Vedere il frammento di codice seguente per 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()

Aggiungere un utente come partecipante al thread di chat

Dopo aver creato un thread, è possibile aggiungere e rimuovere utenti. Aggiungendo utenti, è possibile concedere loro l'accesso per poter inviare messaggi al thread e aggiungere/rimuovere altri partecipanti. Prima di chiamare add, verificare di avere acquisito un nuovo token di accesso e un'identità per tale utente. L'utente dovrà usare il token di accesso per inizializzare il client di chat.

Usare il add metodo di ChatThreadClient per aggiungere uno o più partecipanti al thread di chat. Di seguito sono riportati gli attributi supportati per ogni partecipante del thread:

  • id, obbligatorio, è l'identità del partecipante del thread.
  • displayName, facoltativo, è il nome visualizzato per il partecipante del thread.
  • shareHistoryTime, facoltativo, ora da cui la cronologia delle chat viene condivisa con il partecipante.

Sostituire il commento <ADD A USER> con il codice seguente:

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

Sostituire <USER_ID> con l'ID utente di Servizi di comunicazione dell'utente da aggiungere.

Elencare gli utenti in un thread

Usare il listParticipants metodo per ottenere tutti i partecipanti per un thread di chat specifico.

Sostituire il commento <LIST USERS> con il codice seguente:

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

Notifiche push

Le notifiche push notificano ai client i messaggi in arrivo in un thread di chat in situazioni in cui l'app per dispositivi mobili non è in esecuzione in primo piano. Attualmente l'invio di notifiche push di chat con Hub di notifica è supportato per IOS SDK nella versione 1.3.0. Per informazioni dettagliate, vedere l'articolo Abilitare la notifica push nell'app di chat.

Eseguire il codice

In Xcode premere il pulsante Esegui per compilare ed eseguire il progetto. Nella console è possibile visualizzare l'output del codice e l'output del logger da ChatClient.

Nota: impostare su NoBuild Settings > Build Options > Enable Bitcode . Attualmente AzureCommunicationChat SDK per iOS non supporta l'abilitazione del bitcode, il seguente problema di GitHub sta monitorando questo problema .

Codice di esempio

Trovare il codice finalizzato per questa guida introduttiva in GitHub.

Prerequisiti

Creare un utente

Completare questi passaggi in Power Automate con il flusso di Power Automate aperto in modalità di modifica.

Per aggiungere un nuovo passaggio nel flusso di lavoro usando il connettore di identità di Servizi di comunicazione:

  1. Nella finestra di progettazione, nel passaggio in cui si vuole aggiungere la nuova azione, selezionare Nuovo passaggio. In alternativa, per aggiungere la nuova azione tra i passaggi, spostare il puntatore sulla freccia tra questi passaggi, selezionare il segno più (+) e quindi selezionare Aggiungi un'azione.

  2. Nella casella di ricerca Scegliere un'operazione immettere Identità servizi di comunicazione. Nell'elenco delle azioni selezionare Crea un utente.

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

  3. Immettere il stringa di connessione. Per ottenere l'URL stringa di connessione nella portale di Azure, passare alla risorsa Servizi di comunicazione di Azure. Nel menu della risorsa selezionare Chiavi e quindi selezionare Connessione stringa di Connessione ion. Selezionare l'icona di copia per copiare il stringa di connessione.

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

  4. Immetti un nome per la connessione.

  5. Selezionare Mostra opzioni avanzate e quindi selezionare l'ambito del token. L'azione genera un token di accesso e la relativa ora di scadenza con l'ambito specificato. Questa azione genera anche un ID utente che rappresenta un'identità utente di Servizi di comunicazione.

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

  6. In Token Scopes Item (Elemento ambiti token) selezionare chat (Chat).

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

  7. Seleziona Crea. Vengono visualizzati l'ID utente e un token di accesso.

Creare un thread di chat

  1. Aggiungi una nuova azione.

  2. Nella casella di ricerca Scegliere un'operazione immettere Chat di Servizi di comunicazione. Nell'elenco delle azioni selezionare Crea thread di chat.

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

  3. Immettere l'URL dell'endpoint di Servizi di comunicazione. Per ottenere l'URL dell'endpoint nella portale di Azure, passare alla risorsa Servizi di comunicazione di Azure. Nel menu della risorsa selezionare Chiavi e quindi endpoint.

  4. Immetti un nome per la connessione.

  5. Selezionare il token di accesso generato nella sezione precedente e quindi aggiungere una descrizione dell'argomento del thread di chat. Aggiungere l'utente creato e immettere un nome per il partecipante.

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

Invia un messaggio

  1. Aggiungi una nuova azione.

  2. Nella casella di ricerca Scegliere un'operazione immettere Chat di Servizi di comunicazione. Nell'elenco delle azioni selezionare Invia messaggio al thread di chat.

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

  3. Immettere il token di accesso, l'ID del thread, il contenuto e il nome.

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

Elencare i messaggi dei thread di chat

Per verificare che sia stato inviato correttamente un messaggio:

  1. Aggiungi una nuova azione.

  2. Nella casella di ricerca Scegliere un'operazione immettere Chat di Servizi di comunicazione. Nell'elenco delle azioni selezionare Elenca i messaggi del thread di chat.

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

  3. Immettere il token di accesso e l'ID del thread.

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

Testare l'app per la logica

Per avviare manualmente il flusso di lavoro, sulla barra degli strumenti della finestra di progettazione selezionare Esegui. Il flusso di lavoro crea un utente, rilascia un token di accesso per tale utente e quindi rimuove il token ed elimina l'utente. Per altre informazioni, vedere Come eseguire il flusso di lavoro.

Selezionare ora Elenca i messaggi del thread di chat. Negli output dell'azione verificare la presenza del messaggio inviato.

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

Pulire le risorse del flusso di lavoro

Per pulire il flusso di lavoro dell'app per la logica e le risorse correlate, vedere come pulire le risorse di App per la logica.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate. Altre informazioni sulla pulizia delle risorse.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come:

  • Creare un client di chat
  • Creare un thread con due utenti
  • Inviare un messaggio al thread
  • Ricevere messaggi da un thread
  • Rimuovere utenti da un thread

Provare l'app Chat Hero

Può essere utile vedere anche gli articoli seguenti: