Partager via

Démarrage rapide de l’enregistrement d’appel

  • Article

Ce guide de démarrage rapide vous permet de bien démarrer avec l’enregistrement d’appels pour les appels vocaux et vidéo. Pour commencer à utiliser les API d’enregistrement des appels, vous devez avoir un appel en place. Assurez-vous de bien connaître le SDK de client appelant et/ou d’Automatisation des appels pour créer l’expérience d’appel de l’utilisateur final.

Exemple de code

Vous pouvez télécharger l’exemple d’application à partir de GitHub.

Prérequis

  • Vous devez avoir un compte Azure avec un abonnement actif.
  • Déployez une ressource Azure Communication Services. Enregistrez la chaîne de connexion de votre ressource.
  • Vous abonner aux événements via Azure Event Grid.
  • Télécharger le SDK .NET

Avant de commencer

Les API d’enregistrement d’appel utilisent exclusivement le serverCallId pour lancer l’enregistrement. Il existe quelques méthodes que vous pouvez utiliser pour extraire le serverCallId en fonction de votre scénario :

Scénarios relatifs à l’automatisation des appels

  • Lorsque vous utilisez l’automatisation des appels, vous avez deux options pour obtenir le serverCallId :
    1. Une fois l’appel créé, un élément serverCallId est renvoyé comme propriété de l’événement CallConnected après que l’appel a été établi. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.
    2. Une fois que vous avez répondu à l’appel ou qu’un appel est créé, le serverCallId est retourné en tant que propriété des réponses d’API AnswerCallResult ou CreateCallResult, respectivement.

Scénarios du kit SDK appelant

  • Lors de l’utilisation du kit SDK de client appelant, vous pouvez récupérer le serverCallId à l’aide de la méthode getServerCallId sur l’appel. Utilisez cet exemple pour découvrir comment obtenir le serverCallId à partir du SDK de client appelant.

Commençons par quelques étapes simples !

1. Créer un client d’automatisation des appels

Les API d’enregistrement des appels font partie des bibliothèques d’automatisation des appels Azure Communication Services. Par conséquent, il est nécessaire de créer un client d’automatisation d’appels. Pour créer un client d’automatisation des appels, vous utilisez votre chaîne de connexion Communication Services et la passer à l’objet CallAutomationClient.

CallAutomationClient callAutomationClient = new CallAutomationClient("<ACSConnectionString>");

2. Démarrer l’enregistrement d’une session avec StartRecordingOptions en utilisant l’API « StartAsync »

Utilisez le serverCallId reçu lors du lancement de l’appel.

  • RecordingContent permet de passer le type de contenu de l’enregistrement. Utiliser l’audio
  • RecordingChannel permet de passer le type de canal de l’enregistrement. Utilisez de l’audio mixte ou séparé.
  • RecordingFormat permet de passer le format de l’enregistrement. Utilisez wav.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    RecordingStateCallbackUri = new Uri("<CallbackUri>");
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.1. Démarrer l’enregistrement – Apporter votre propre Stockage Blob Azure

Démarrez l’enregistrement avec votre propre Stockage Blob Azure défini pour stocker le fichier d’enregistrement une fois ce dernier terminé.

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
   RecordingContent = RecordingContent.Audio,
   RecordingChannel = RecordingChannel.Unmixed,
   RecordingFormat = RecordingFormat.Wav,
   RecordingStateCallbackUri = new Uri("<CallbackUri>"),
   RecordingStorage = RecordingStorage.CreateAzureBlobContainerRecordingStorage(new Uri("<YOUR_STORAGE_CONTAINER_URL>"))
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.2. Démarrer l’enregistrement d’une session avec le mode Pause activé en utilisant l’API « StartAsync »

Remarque

Vous devez reprendre les enregistrements pour le fichier d’enregistrement à générer.

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    PauseOnStart = true,
    RecordingStateCallbackUri = new Uri("<CallbackUri>");
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.3. Uniquement pour Séparé - Spécifiez un utilisateur sur un canal 0

Pour produire des fichiers d’enregistrement audio non mixés, vous pouvez utiliser la fonctionnalité AudioChannelParticipantOrdering pour spécifier l’utilisateur que vous souhaitez enregistrer sur le canal 0. Les autres participants sont affectés à un canal à mesure qu’ils parlent. Si vous utilisez RecordingChannel.Unmixed, mais pas AudioChannelParticipantOrdering, l’enregistrement des appels attribue le canal 0 au premier participant qui parle.

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    RecordingStateCallbackUri = new Uri("<CallbackUri>"),
    AudioChannelParticipantOrdering = { new CommunicationUserIdentifier("<ACS_USER_MRI>") }
    
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording().StartAsync(recordingOptions);

2.4. Uniquement pour Séparé : spécifier une affinité de canal

var channelAffinity = new ChannelAffinity(new CommunicationUserIdentifier("<ACS_USER_MRI>")) { Channel = 0};
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
   RecordingContent = RecordingContent.Audio,
   RecordingChannel = RecordingChannel.Unmixed,
   RecordingFormat = RecordingFormat.Wav,
   RecordingStateCallbackUri = new Uri("<CallbackUri>"),
   ChannelAffinity = new List<ChannelAffinity>{ channelAffinity }
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording().StartAsync(recordingOptions);

La réponse de l’API StartAsync contient le recordingId de la session d’enregistrement.

3. Arrêter l’enregistrement d’une session en utilisant l’API « StopAsync »

Utilisez le recordingId reçu en réponse à StartAsync.

var stopRecording = await callAutomationClient.GetCallRecording().StopAsync(recordingId);

4. Suspendre l’enregistrement d’une session en utilisant l’API « PauseAsync »

Utilisez le recordingId reçu en réponse à StartAsync.

var pauseRecording = await callAutomationClient.GetCallRecording ().PauseAsync(recordingId);

5. Reprendre l’enregistrement d’une session en utilisant l’API « ResumeAsync »

Utilisez le recordingId reçu en réponse à StartAsync.

var resumeRecording = await callAutomationClient.GetCallRecording().ResumeAsync(recordingId);

6. Télécharger le fichier d’enregistrement avec l’API « DownloadToAsync »

Utilisez un Webhook Azure Event Grid ou une autre action déclenchée pour informer vos services lorsque le média enregistré est prêt à être téléchargé.

Une notification Event Grid Microsoft.Communication.RecordingFileStatusUpdated est publiée lorsqu’un enregistrement est prêt pour la récupération, en général quelques minutes après la fin du processus d’enregistrement (par exemple, réunion terminée, enregistrement arrêté). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation utilisés pour récupérer les informations multimédias enregistrées et un fichier de métadonnées d’enregistrement.

Exemple de schéma d’événement :

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

Utilisez l’API DownloadToAsync pour télécharger le média enregistré.

var recordingDownloadUri = new Uri(contentLocation);
var response = await callAutomationClient.GetCallRecording().DownloadToAsync(recordingDownloadUri, fileName);

L’emplacement de téléchargement (downloadLocation) de l’enregistrement peut être récupéré à partir de l’attribut contentLocation de recordingChunk. La méthode DownloadToAsync télécharge le contenu dans le nom de fichier fourni.

7. Supprimer le contenu d’enregistrement en utilisant l’API « DeleteAsync »

Utilisez l’API DeleteAsync pour supprimer le contenu d’enregistrement (par exemple, média et métadonnées enregistrés)

var recordingDeleteUri = new Uri(deleteLocation);
var response = await callAutomationClient.GetCallRecording().DeleteAsync(recordingDeleteUri);

Exemple de code

Vous pouvez télécharger l’exemple d’application à partir de GitHub.

Prérequis

  • Vous devez avoir un compte Azure avec un abonnement actif.
  • Déployez une ressource Azure Communication Services. Enregistrez la chaîne de connexion de votre ressource.
  • Vous abonner aux événements via Azure Event Grid.
  • Téléchargez le SDK Java

Avant de commencer

Les API d’enregistrement d’appel utilisent exclusivement le serverCallId pour lancer l’enregistrement. Il existe quelques méthodes que vous pouvez utiliser pour extraire le serverCallId en fonction de votre scénario :

Scénarios relatifs à l’automatisation des appels

  • Lorsque vous utilisez l’automatisation des appels, vous avez deux options pour obtenir le serverCallId :
    1. Une fois l’appel créé, un élément serverCallId est renvoyé comme propriété de l’événement CallConnected après que l’appel a été établi. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.
    2. Une fois que vous avez répondu à l’appel ou qu’un appel est créé, le serverCallId est retourné en tant que propriété des réponses d’API AnswerCallResult ou CreateCallResult, respectivement.

Scénarios du kit SDK appelant

  • Lors de l’utilisation du kit SDK de client appelant, vous pouvez récupérer le serverCallId à l’aide de la méthode getServerCallId sur l’appel. Utilisez cet exemple pour découvrir comment obtenir le serverCallId à partir du SDK de client appelant.

Commençons par quelques étapes simples !

1. Créer un client d’automatisation des appels

Les API d’enregistrement des appels font partie des bibliothèques d’automatisation des appels Azure Communication Services. Par conséquent, il est nécessaire de créer un client d’automatisation d’appels. Pour créer un client d’automatisation des appels, vous allez utiliser votre chaîne de connexion Communication Services et la passer à l’objet CallAutomationClient.

CallAutomationClient callAutomationClient = new CallAutomationClientBuilder()
            .connectionString("<acsConnectionString>")
            .buildClient();

2. Démarrer l’enregistrement d’une session avec StartRecordingOptions en utilisant l’API « startWithResponse »

Utilisez le serverCallId reçu lors du lancement de l’appel.

  • RecordingContent permet de passer le type de contenu de l’enregistrement. Utiliser AUDIO
  • RecordingChannel permet de passer le type de canal de l’enregistrement. Utilisez MIXED ou UNMIXED.
  • RecordingFormat permet de passer le format de l’enregistrement. Utilisez WAV.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>");

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.1. Démarrer l’enregistrement – Apporter votre propre Stockage Blob Azure

Démarrez la session d’enregistrement avec votre propre Stockage Blob Azure pour stocker le fichier d’enregistrement une fois ce dernier terminé.

       StartRecordingOptions recordingOptions = new StartRecordingOptions(callLocator)
       .setRecordingChannel(RecordingChannel.MIXED)
       .setRecordingContent(RecordingContent.AUDIO_VIDEO)
       .setRecordingFormat(RecordingFormat.MP4)
       .setRecordingStorage(new AzureBlobContainerRecordingStorage("<YOUR_STORAGE_CONTAINER_URL>"));
 
       // //start recording
       RecordingStateResult result = callRecording.start(recordingOptions);

2.2. Démarrer l’enregistrement d’une session avec le mode Pause activé en utilisant l’API « StartAsync »

Remarque

Vous devez reprendre les enregistrements pour le fichier d’enregistrement à générer.

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
                    .setPauseOnStart(true)
                    .setAudioChannelParticipantOrdering(List.of(new CommunicationUserIdentifier("<participantMri>")));

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.3. Uniquement pour Séparé - Spécifiez un utilisateur sur un canal 0

Pour produire des fichiers d’enregistrement audio non mixés, vous pouvez utiliser la fonctionnalité AudioChannelParticipantOrdering pour spécifier l’utilisateur que vous souhaitez enregistrer sur le canal 0. Les autres participants seront affectés à un canal à mesure qu’ils parlent. Si vous utilisez RecordingChannel.Unmixed mais pas AudioChannelParticipantOrdering, l’enregistrement des appels attribuera le canal 0 au premier participant qui parle.

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
                    .setAudioChannelParticipantOrdering(List.of(new CommunicationUserIdentifier("<participantMri>")));

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.4. Uniquement pour Séparé : spécifier une affinité de canal

ChannelAffinity channelAffinity = new ChannelAffinity()
.setParticipant(new PhoneNumberIdentifier("RECORDING_ID"))
.setChannel(0);
List<ChannelAffinity> channelAffinities = Arrays.asList(channelAffinity);

StartRecordingOptions startRecordingOptions = new StartRecordingOptions(new ServerCallLocator(SERVER_CALL_ID))
   .setRecordingChannel(RecordingChannel.UNMIXED)
   .setRecordingFormat(RecordingFormat.WAV)
   .setRecordingContent(RecordingContent.AUDIO)
   .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
   .setChannelAffinity(channelAffinities);
Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startRecordingWithResponse(recordingOptions, null);

La réponse de l’API startWithResponse contient le recordingId de la session d’enregistrement.

3. Arrêter l’enregistrement d’une session en utilisant l’API « stopWithResponse »

Utilisez le recordingId reçu en réponse à startWithResponse.

Response<Void> response = callAutomationClient.getCallRecording()
               .stopWithResponse(response.getValue().getRecordingId(), null);

4. Suspendre l’enregistrement d’une session en utilisant l’API « pauseWithResponse »

Utilisez le recordingId reçu en réponse à startWithResponse.

Response<Void> response = callAutomationClient.getCallRecording()
              .pauseWithResponse(response.getValue().getRecordingId(), null);

5. Reprendre l’enregistrement d’une session en utilisant l’API « resumeResponse »

Utilisez le recordingId reçu en réponse à startWithResponse.

Response<Void> response = callAutomationClient.getCallRecording()
               .resumeWithResponse(response.getValue().getRecordingId(), null);

6. Télécharger le fichier d’enregistrement à l’aide de l’API « downloadToWithResponse »

Utilisez un Webhook Azure Event Grid ou une autre action déclenchée pour informer vos services lorsque le média enregistré est prêt à être téléchargé.

Une notification Event Grid Microsoft.Communication.RecordingFileStatusUpdated est publiée lorsqu’un enregistrement est prêt pour la récupération, en général quelques minutes après la fin du processus d’enregistrement (par exemple, réunion terminée, enregistrement arrêté). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation utilisés pour récupérer les informations multimédias enregistrées et un fichier de métadonnées d’enregistrement.

Voici un exemple du schéma d’événement.

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

Utilisez la méthode downloadToWithResponse de la classe CallRecording pour télécharger le média enregistré. Les paramètres suivants sont pris en charge pour la méthode downloadToWithResponse :

  • contentLocation : URL d’Azure Communication Services où se trouve le contenu.
  • destinationPath : emplacement du fichier.
  • parallelDownloadOptions : objet ParallelDownloadOptions facultatif permettant de modifier la façon dont le téléchargement parallèle fonctionne.
  • overwrite : valeur True pour remplacer le fichier s’il existe.
  • context : contexte représentant le contexte de la requête.
Boolean overwrite = true;
ParallelDownloadOptions parallelDownloadOptions = null;
Context context = null;

String filePath = String.format(".\\%s.%s", documentId, fileType);
Path destinationPath = Paths.get(filePath);

Response<Void> downloadResponse = callAutomationClient.getCallRecording().downloadToWithResponse(contentLocation, destinationPath, parallelDownloadOptions, overwrite, context);

L’emplacement du contenu et les ID de document pour les fichiers d’enregistrement peuvent être récupérés respectivement dans les champs contentLocation et documentId pour chaque recordingChunk.

7. Supprimer l’enregistrement d’un contenu en utilisant l’API « deleteWithResponse »

Utilisez la méthode deleteWithResponse de la classe CallRecording pour supprimer le média enregistré. Les paramètres suivants sont pris en charge pour la méthode deleteWithResponse :

  • deleteLocation : URL d’Azure Communication Services où se trouve le contenu à supprimer.
  • context : contexte représentant le contexte de la requête.
Response<Void> deleteResponse = callAutomationClient.getCallRecording().deleteWithResponse(deleteLocation, context);

L’emplacement de suppression de l’enregistrement peut être extrait du champ deleteLocation de l’événement Event Grid.

Exemple de code

Vous pouvez télécharger l’exemple d’application à partir de GitHub.

Prérequis

  • Vous devez avoir un compte Azure avec un abonnement actif.
  • Déployez une ressource Azure Communication Services. Enregistrez la chaîne de connexion de votre ressource.
  • Vous abonner aux événements via Azure Event Grid.
  • Python 3.7+.

Avant de commencer

Les API d’enregistrement d’appel utilisent exclusivement le serverCallId pour lancer l’enregistrement. Il existe quelques méthodes que vous pouvez utiliser pour extraire le serverCallId en fonction de votre scénario :

Scénarios relatifs à l’automatisation des appels

  • Lorsque vous utilisez l’automatisation des appels, vous avez deux options pour obtenir le serverCallId :
    1. Une fois l’appel créé, un élément serverCallId est renvoyé comme propriété de l’événement CallConnected après que l’appel a été établi. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.
    2. Une fois que vous avez répondu à l’appel ou qu’un appel est créé, le serverCallId est retourné en tant que propriété des réponses d’API AnswerCallResult ou CreateCallResult, respectivement.

Scénarios du kit SDK appelant

Commençons par quelques étapes simples !

1. Créer un client d’automatisation des appels

Les API d’enregistrement des appels font partie des bibliothèques d’automatisation des appels Azure Communication Services. Par conséquent, il est nécessaire de créer un client d’automatisation d’appels. Pour créer un client d’automatisation des appels, vous allez utiliser votre chaîne de connexion Communication Services et la passer à l’objet CallAutomationClient.

call_automation_client = CallAutomationClient.from_connection_string("<ACSConnectionString>")

2. Démarrer l’API start_recording d’enregistrement de session

Utilisez le serverCallId reçu lors du lancement de l’appel.

  • RecordingContent permet de passer le type de contenu de l’enregistrement. Utiliser l’audio
  • RecordingChannel permet de passer le type de canal de l’enregistrement. Utilisez de l’audio mixte ou séparé.
  • RecordingFormat permet de passer le format de l’enregistrement. Utilisez wav.
response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>")

2.1. Démarrer l’enregistrement – Apporter votre propre Stockage Blob Azure

Démarrez l’enregistrement avec votre propre Stockage Blob Azure défini pour stocker le fichier d’enregistrement une fois ce dernier terminé.

response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
                   recording_content_type = RecordingContent.Audio,
                   recording_channel_type = RecordingChannel.Unmixed,
                   recording_format_type = RecordingFormat.Wav,
                   recording_state_callback_url = "<CallbackUri>",
                   recording_storage = AzureBlobContainerRecordingStorage(container_url="<YOUR_STORAGE_CONTAINER_URL>"))

2.2. Démarrer l’enregistrement d’une session avec le mode Pause activé en utilisant l’API « StartAsync »

Remarque

Vous devez reprendre les enregistrements pour le fichier d’enregistrement à générer.

response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            pause_on_start = true,
            recording_state_callback_url = "<CallbackUri>")

2.3. Uniquement pour Séparé - Spécifiez un utilisateur sur un canal 0

Pour produire des fichiers d’enregistrement audio non mixés, vous pouvez utiliser la fonctionnalité AudioChannelParticipantOrdering pour spécifier l’utilisateur que vous souhaitez enregistrer sur le canal 0. Les autres participants seront affectés à un canal à mesure qu’ils parlent. Si vous utilisez RecordingChannel.Unmixed mais pas AudioChannelParticipantOrdering, l’enregistrement des appels attribuera le canal 0 au premier participant qui parle.

response =  call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>",
            audio_channel_participant_ordering=[CommunicationUserIdentifier(id="<ACS_USER_MRI>")])

2.4. Uniquement pour Séparé : spécifier une affinité de canal

_channel_affinity = ChannelAffinity(target_participant=CommunicationUserIdentifier("<ACS_USER_MRI>"), channel=0)

response =  call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>",
            channel_affinity=[_channel_affinity])

La réponse de l’API StartAsync contient le recordingId de la session d’enregistrement.

3. Arrêter l’enregistrement de session à l’aide de l’API « stop_recording »

Utilisez le recording_id reçu en réponse à start_recording.

stop_recording = call_automation_client.stop_recording(recording_id = recording_id)

4. Suspendre la session d’enregistrement à l’aide de l’API « pause_recording »

Utilisez le recording_id reçu en réponse à start_recording.

pause_recording = call_automation_client.pause_recording(recording_id = recording_id)

5. Reprendre la session d’enregistrement à l’aide de l’API « resume_recording »

Utilisez le recording_id reçu en réponse à start_recording.

resume_recording = call_automation_client.resume_recording(recording_id = recording_id)

6. Télécharger le fichier d’enregistrement avec l’API « download_recording »

Utilisez un Webhook Azure Event Grid ou une autre action déclenchée pour informer vos services lorsque le média enregistré est prêt à être téléchargé.

Une notification Event Grid Microsoft.Communication.RecordingFileStatusUpdated est publiée lorsqu’un enregistrement est prêt pour la récupération, en général quelques minutes après la fin du processus d’enregistrement (par exemple, réunion terminée, enregistrement arrêté). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation utilisés pour récupérer les informations multimédias enregistrées et un fichier de métadonnées d’enregistrement.

Voici un exemple du schéma d’événement.

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

Utilisez l’API download_recording pour télécharger le média enregistré.

response = recording_data = call_automation_client.download_recording(content_location)

with open("<file_name>", "wb") as binary_file:
    binary_file.write(recording_data.read())

L’emplacement de téléchargement (downloadLocation) de l’enregistrement peut être récupéré à partir de l’attribut contentLocation de recordingChunk. La méthode download_recording télécharge le contenu en octets.

7. Supprimer le contenu d’enregistrement avec l’API « delete_recording »

Utilisez l’API delete_recording pour supprimer le contenu d’enregistrement (par exemple, média et métadonnées enregistrés)

response = call_automation_client.delete_recording(delete_location);

Exemple de code

Vous pouvez télécharger l’exemple d’application à partir de GitHub.

Prérequis

  • Vous devez avoir un compte Azure avec un abonnement actif.
  • Déployez une ressource Azure Communication Services. Enregistrez la chaîne de connexion de votre ressource.
  • Vous abonner aux événements via Azure Event Grid.
  • Versions Node.js Active LTS et Maintenance LTS (8.11.1 et 10.14.1 recommandées)

Avant de commencer

Les API d’enregistrement d’appel utilisent exclusivement le serverCallId pour lancer l’enregistrement. Il existe quelques méthodes que vous pouvez utiliser pour extraire le serverCallId en fonction de votre scénario :

Scénarios relatifs à l’automatisation des appels

  • Lorsque vous utilisez l’automatisation des appels, vous avez deux options pour obtenir le serverCallId :
    1. Une fois l’appel créé, un élément serverCallId est renvoyé comme propriété de l’événement CallConnected après que l’appel a été établi. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.
    2. Une fois que vous avez répondu à l’appel ou qu’un appel est créé, le serverCallId est retourné en tant que propriété des réponses d’API AnswerCallResult ou CreateCallResult, respectivement.

Scénarios du kit SDK appelant

  • Lors de l’utilisation du kit SDK de client appelant, vous pouvez récupérer le serverCallId à l’aide de la méthode getServerCallId sur l’appel. Utilisez cet exemple pour découvrir comment obtenir le serverCallId à partir du SDK de client appelant.

Commençons par quelques étapes simples !

1. Créer un client d’automatisation des appels

Les API d’enregistrement des appels font partie des bibliothèques d’automatisation des appels Azure Communication Services. Par conséquent, il est nécessaire de créer un client d’automatisation d’appels. Pour créer un client d’automatisation des appels, vous allez utiliser votre chaîne de connexion Communication Services et la passer à l’objet CallAutomationClient.

const callAutomationClient = new CallAutomationClient.CallAutomationClient("<ACSConnectionString>");

2. Démarrer l’enregistrement d’une session avec StartRecordingOptions en utilisant l’API « StartAsync »

Utilisez le serverCallId reçu lors du lancement de l’appel.

  • RecordingContent permet de passer le type de contenu de l’enregistrement. Utiliser l’audio
  • RecordingChannel permet de passer le type de canal de l’enregistrement. Utilisez de l’audio mixte ou séparé.
  • RecordingFormat permet de passer le format de l’enregistrement. Utilisez wav.
var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>"
};
var response = await callAutomationClient.getCallRecording().start(options);

2.1. Démarrer l’enregistrement – Apporter votre propre Stockage Blob Azure

Démarrez l’enregistrement avec votre propre Stockage Blob Azure défini pour stocker le fichier d’enregistrement une fois ce dernier terminé.

const recordingStorageKind: RecordingStorageKind = "azureBlobStorage"
const recordingStorage: RecordingStorage = { 
       recordingStorageKind: recordingStorageKind, 
       recordingDestinationContainerUrl: "<YOUR_STORAGE_CONTAINER_URL>"
   }
var options: StartRecordingOptions = {
       callLocator: callLocator,
       recordingContent: "audio",
       recordingChannel:"unmixed",
       recordingFormat: "wav",
       recordingStateCallbackEndpointUrl: "<CallbackUri>",
       recordingStorage: recordingStorage
   };
var response = await callAutomationClient.getCallRecording().start(options);

2.2. Démarrer l’enregistrement d’une session avec le mode Pause activé en utilisant l’API « StartAsync »

Remarque

Vous devez reprendre les enregistrements pour le fichier d’enregistrement à générer.

var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  pauseOnStart: true
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  audioChannelParticipantOrdering:[{communicationUserId: "<ACS_USER_MRI>"}]
};
var response = await callAutomationClient.getCallRecording().start(options);

2.3. Uniquement pour Séparé - Spécifiez un utilisateur sur un canal 0

Pour produire des fichiers d’enregistrement audio non mixés, vous pouvez utiliser la fonctionnalité AudioChannelParticipantOrdering pour spécifier l’utilisateur que vous souhaitez enregistrer sur le canal 0. Les autres participants seront affectés à un canal à mesure qu’ils parlent. Si vous utilisez RecordingChannel.Unmixed mais pas AudioChannelParticipantOrdering, l’enregistrement des appels attribuera le canal 0 au premier participant qui parle.

var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  audioChannelParticipantOrdering:[{communicationUserId: "<ACS_USER_MRI>"}]
};
var response = await callAutomationClient.getCallRecording().start(options);

2.4. Uniquement pour Séparé : spécifier une affinité de canal

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  ChannelAffinity:
  [
    {
      channel:0,
      targetParticipant:{communicationUserId: "<ACS_USER_MRI>"}
    }
  ]
};
var response = await callAutomationClient.getCallRecording().start(options);

La réponse de l’API StartAsync contient le recordingId de la session d’enregistrement.

3. Arrêter l’enregistrement d’une session en utilisant l’API « stop »

Utilisez le recordingId reçu en réponse à start.

var stopRecording = await callAutomationClient.getCallRecording().stop(recordingId);

4. Suspendre l’enregistrement d’une session en utilisant l’API « pause »

Utilisez le recordingId reçu en réponse à start.

var pauseRecording = await callAutomationClient.getCallRecording().pause(recordingId);

5. Reprendre l’enregistrement d’une session en utilisant l’API « ResumeAsync »

Utilisez le recordingId reçu en réponse à start.

var resumeRecording = await callAutomationClient.getCallRecording().resume(recordingId);

6. Télécharger le fichier d’enregistrement avec l’API « DownloadToAsync »

Utilisez un Webhook Azure Event Grid ou une autre action déclenchée pour informer vos services lorsque le média enregistré est prêt à être téléchargé.

Une notification Event Grid Microsoft.Communication.RecordingFileStatusUpdated est publiée lorsqu’un enregistrement est prêt pour la récupération, en général quelques minutes après la fin du processus d’enregistrement (par exemple, réunion terminée, enregistrement arrêté). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation utilisés pour récupérer les informations multimédias enregistrées et un fichier de métadonnées d’enregistrement.

Voici un exemple du schéma d’événement.

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

Utilisez l’API downloadToPath pour télécharger le média enregistré.

var response = await callAutomationClient.getCallRecording().downloadToPath(contentLocation, fileName);

L’emplacement de téléchargement (downloadLocation) de l’enregistrement peut être récupéré à partir de l’attribut contentLocation de recordingChunk. Méthode DownloadToAsync : téléchargez le contenu dans le nom de fichier fourni.

7. Supprimer le contenu d’enregistrement en utilisant l’API « DeleteAsync »

Utilisez l’API delete pour supprimer le contenu d’enregistrement (par exemple, média et métadonnées enregistrés)

var response = await callAutomationClient.getCallRecording().delete(deleteLocation);

Nettoyer les ressources

Si vous voulez nettoyer et supprimer un abonnement Communication Services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées. Apprenez-en davantage sur le nettoyage des ressources.

Étapes suivantes

Pour plus d’informations, consultez les articles suivants :