Partage via

Démarrage rapide de l’enregistrement d’appel

  • Article

Cet article décrit l’enregistrement d’appel pour les appels vocaux et vidéo. Pour commencer à utiliser les API d’enregistrement des appels, vous devez avoir un appel en place. Pour générer l’expérience d’appel de l’utilisateur final, assurez-vous de bien connaître le Kit de développement logiciel (SDK) du client appelant et l’Automatisation des appels.

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. Lorsque vous établissez un appel, il retourne un serverCallId comme propriété de l’événement CallConnected après l’établissement d’un appel. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.

  2. Lorsque vous répondez à l’appel ou qu’un appel est créé, il retourne le serverCallId comme 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 faciles.

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. Vous devez créer un client d’automatisation des appels.

Pour créer un client d’automatisation des appels, utilisez votre chaîne de connexion Communication Services et passez-la à 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.

  • Utilisez RecordingContent pour passer le type de contenu d’enregistrement. Utiliser AUDIO.
  • Utilisez RecordingChannel pour passer le type de chaîne d’enregistrement. Utilisez MIXED ou UNMIXED.
  • Utilisez RecordingFormat pour passer le format de l’enregistrement. Utiliser 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 Stockage Blob Azure désigné pour stocker le fichier enregistré une fois l’enregistrement 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>"))
    ExternalStorage = new BlobStorage(new Uri("<Insert Container / Blob Uri>"))
};
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 la session d’enregistrement avec l’API StopAsync

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

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

4. Interrompre la session d’enregistrement avec l’API PauseAsync

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

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

5. Reprendre la session d’enregistrement avec 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 traitement de l’enregistrement (telle que la fin d’une réunion ou l’arrêt d’un enregistrement). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation, que vous pouvez utiliser pour récupérer les médias enregistrés 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 les médias enregistrés.

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

Récupérez le downloadLocation de l’enregistrement à partir de l’attribut contentLocation du recordingChunk. Utilisez la méthode DownloadToAsync pour télécharger le contenu vers un nom de fichier indiqué.

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

Utilisez l’API DeleteAsync pour supprimer le contenu d’enregistrement (dont les médias enregistrés et les métadonnées).

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 un appel créé, un serverCallId est renvoyé comme propriété de l’événement CallConnected une fois l’appel é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 faciles.

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. Vous devez créer un client d’automatisation des appels.

Pour créer un client d’automatisation des appels, utilisez votre chaîne de connexion Communication Services et passez-la à l’objet CallAutomationClient.

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

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

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

  • Utilisez RecordingContent pour passer le type de contenu d’enregistrement. Utiliser AUDIO.
  • Utilisez RecordingChannel pour passer le type de chaîne d’enregistrement. Utilisez MIXED ou UNMIXED.
  • Utilisez RecordingFormat pour passer le format de l’enregistrement. Utiliser 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 l’enregistrement avec votre Stockage Blob Azure désigné pour stocker le fichier enregistré une fois l’enregistrement terminé.

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

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

Remarque

Vous devez reprendre les enregistrements pour que le fichier d’enregistrement soit généré.

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 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>"))
                    .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 la session d’enregistrement avec l’API stopWithResponse

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

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

4. Interrompre la session d’enregistrement avec l’API pauseWithResponse

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

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

5. Reprendre la session d’enregistrement avec l’API resumeWithResponse

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 avec 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. Cela se passe en général quelques minutes après la fin du processus d’enregistrement (telle que la fin d’une réunion ou l’arrêt d’un enregistrement). Les notifications d’événements d’enregistrement incluent des éléments contentLocation et metadataLocation, que vous pouvez utiliser pour récupérer les médias enregistrés et un fichier de métadonnées d’enregistrement.

Le code suivant est un 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 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 pour modifier le fonctionnement du téléchargement parallèle.
  • 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 le contenu d’enregistrement en utilisant l’API deleteWithResponse

Utilisez la méthode deleteWithResponse de la classe CallRecording pour supprimer le média enregistré. Paramètres 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 un appel créé, un serverCallId est renvoyé comme propriété de l’événement CallConnected une fois l’appel établi. Découvrez comment Obtenir l’événement CallConnected à partir du SDK Automatisation des appels.
    2. Une fois que vous répondez à l’appel ou qu’un appel est créé, il retourne le serverCallId comme 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, utilisez votre chaîne de connexion Communication Services et passez-la à 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.

  • Utilisez RecordingContent pour passer le type de contenu d’enregistrement. Utiliser AUDIO.
  • Utilisez RecordingChannel pour passer le type de chaîne d’enregistrement. Utilisez MIXED ou UNMIXED.
  • Utilisez RecordingFormat pour passer le format de l’enregistrement. Utiliser 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 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.

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. Cela se passe en général quelques minutes après la fin du processus d’enregistrement (telle que la fin d’une réunion ou l’arrêt d’un enregistrement). 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.

Le code suivant est un 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 download_recording pour télécharger les médias enregistrés.

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. Utilisez la méthode download_recording pour télécharger 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, dont les médias enregistrés et les métadonnées.

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 un appel créé, un serverCallId est renvoyé comme propriété de l’événement CallConnected une fois l’appel établi. Découvrez comment Obtenir un événement CallConnected à partir du Kit de développement logiciel (SDK) d’automatisation des appels.
    2. Une fois que vous répondez à l’appel ou qu’un appel est créé, il retourne le serverCallId comme 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 un serverCallId à partir du Kit de développement logiciel (SDK) du 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, utilisez votre chaîne de connexion Communication Services et passez-la à 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.

  • Utilisez RecordingContent pour passer le type de contenu d’enregistrement. Utiliser AUDIO.
  • Utilisez RecordingChannel pour passer le type de chaîne d’enregistrement. Utilisez MIXED ou UNMIXED.
  • Utilisez RecordingFormat pour passer le format de l’enregistrement. Utiliser 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 Stockage Blob Azure désigné pour stocker le fichier enregistré une fois l’enregistrement 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 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.

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. Cela se passe en général quelques minutes après la fin du processus d’enregistrement (telle que la fin d’une réunion ou l’arrêt d’un enregistrement). 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.

Le code suivant est un 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 downloadToPath pour télécharger les médias enregistrés.

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. Utilisez la méthode DownloadToAsync pour télécharger le contenu vers un nom de fichier indiqué.

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 :