Schnellstart: Anrufaufzeichnungs-API

Artikel
02/20/2025

In diesem Artikel wird die Anrufaufzeichnung für Sprach- und Videoanrufe beschrieben. Um mit der Verwendung der Anrufaufzeichnungs-APIs zu beginnen, benötigen Sie einen aktiven Anruf. Stellen Sie sicher, dass Sie mit dem Calling Client SDK und/oder der Anrufautomatisierung vertraut sind, damit Sie die Anruferfahrung für Endbenutzende erstellen können.

Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Voraussetzungen

Sie benötigen ein Azure-Konto mit einem aktiven Abonnement.
Stellen Sie eine Communication Services-Ressource bereit. Notieren Sie die Verbindungszeichenfolge Ihrer Ressource.
Abonnieren Sie Ereignisse über Azure Event Grid.
Laden Sie das .NET SDK herunter.

Bevor Sie beginnen

Anrufaufzeichnungs-APIs verwenden ausschließlich serverCallId zum Initiieren der Aufzeichnung. Je nach Szenario gibt es mehrere Methoden, mit denen Sie serverCallId abrufen können:

Szenarien für die Anrufautomatisierung

Bei Verwendung der Anrufautomatisierung haben Sie zwei Optionen zum Abrufen der serverCallId:

Wenn Sie einen Aufruf aufbauen, wird ein serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Aufruf aufgebaut wurde. Im Anrufautomatisierungs-SDK erfahren Sie mehr über das Get CallConnected-Ereignis.
Sobald Sie den Aufruf beantworten oder einen Aufruf erstellt haben, wird serverCallId als Eigenschaft der AnswerCallResult- bzw. CreateCallResult-API-Antwort zurückgegeben.

SDK-Anrufszenarien

Bei Verwendung des Calling Client SDK können Sie die serverCallId abrufen, indem Sie die getServerCallId-Methode für den Anruf verwenden. In diesem Beispiel erfahren Sie, wie Sie serverCallId über das Calling Client SDK abrufen.

Beginnen Sie mit einigen einfachen Schritten.

1. Erstellen eines Anrufautomatisierungsclients

APIs für die Anrufaufzeichnung sind Teil der Anrufautomatisierungsbibliotheken von Azure Communication Services. Sie müssen einen Anrufautomatisierungsclient erstellen.

Um einen Anrufautomatisierungsclient zu erstellen, verwenden Sie Ihre Communication Services-Verbindungszeichenfolge und übergeben sie an das CallAutomationClient-Objekt.

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

2. Starten der Aufzeichnungssitzung mit StartRecordingOptions mithilfe der „StartAsync“-API

Verwenden Sie die Serveranruf-ID (serverCallId), die während der Initiierung des Aufrufs empfangen wurde.

Verwenden Sie RecordingContent, um den Aufzeichnungsinhaltstyp zu übergeben. Verwenden Sie AUDIO.
Verwenden Sie RecordingChannel, um den Aufzeichnungskanaltyp zu übergeben. Verwenden Sie MIXED oder UNMIXED.
Verwenden Sie RecordingFormat, um das Format der Aufzeichnung zu übergeben. Verwenden Sie 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. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

Starten Sie die Aufzeichnung mit Ihrem festgelegten Azure Blob Storage, um die aufgezeichnete Datei zu speichern, sobald die Aufzeichnung abgeschlossen ist.

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. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

Hinweis

Aufzeichnungen müssen fortgesetzt werden, damit eine Aufzeichnungsdatei generiert wird.

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. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

Zum Erstellen ungemischter Audioaufzeichnungsdateien können Sie mithilfe der Funktion AudioChannelParticipantOrdering angeben, welche Benutzer Sie auf Kanal 0 aufzeichnen möchten. Die restlichen Teilnehmer*innen werden einem Kanal zugewiesen, sobald sie sprechen. Wenn Sie RecordingChannel.Unmixed verwenden, aber nicht AudioChannelParticipantOrdering, weist die Anrufaufzeichnung den Kanal 0 dem ersten sprechenden Teilnehmer bzw. der ersten sprechenden Teilnehmerin zu.

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. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

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

Die StartAsync-API-Antwort enthält die Aufzeichnungs-ID (recordingId) der Aufzeichnungssitzung.

3. Beenden der Aufzeichnung der Sitzung mithilfe der `StopAsync`-API

Verwenden Sie die recordingId, die als Antwort auf StartAsync empfangen wurde.

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

4. Anhalten der Aufzeichnung der Sitzung mithilfe der `PauseAsync`-API

Verwenden Sie die recordingId, die als Antwort auf StartAsync empfangen wurde.

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

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der `ResumeAsync`-API

Verwenden Sie die recordingId, die als Antwort auf StartAsync empfangen wurde.

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

6. Herunterladen der Aufzeichnungsdatei mit der `DownloadToAsync`-API

Verwenden Sie einen Azure Event Grid-Webhook oder eine andere ausgelöste Aktion, um Ihre Dienste zu benachrichtigen, wenn die aufgezeichneten Medien zum Download bereit stehen.

Eine Event Grid-Benachrichtigung (Microsoft.Communication.RecordingFileStatusUpdated) wird veröffentlicht, wenn eine Aufzeichnung abrufbereit ist. Dies ist in der Regel wenige Minuten nach Abschluss der Bearbeitung der Aufzeichnung der Fall, also beispielsweise nach dem Ende der Besprechung oder nach dem Beenden der Aufzeichnung. Aufzeichnungsereignisbenachrichtigungen enthalten contentLocation und metadataLocation, mit denen sowohl aufgezeichnete Medien als auch eine Metadatendatei zur Aufzeichnung abgerufen werden können.

Beispiel für das Ereignisschema:

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

Verwenden Sie die DownloadToAsync-API zum Herunterladen der aufgezeichneten Medien.

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

Rufen Sie downloadLocation für die Aufzeichnung aus dem Attribut contentLocation von recordingChunk ab. Verwenden Sie die DownloadToAsync-Methode, um den Inhalt in einen bereitgestellten Dateinamen herunterzuladen.

7. Löschen von Aufzeichnungsinhalten mithilfe der `DeleteAsync`-API

Verwenden Sie die DeleteAsync-API, um den Aufzeichnungsinhalt, z. B. aufgezeichnete Medien und Metadaten zu löschen.

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

Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Voraussetzungen

Sie benötigen ein Azure-Konto mit einem aktiven Abonnement.
Stellen Sie eine Communication Services-Ressource bereit. Notieren Sie die Verbindungszeichenfolge Ihrer Ressource.
Abonnieren Sie Ereignisse über Azure Event Grid.
Herunterladen des Java SDK

Vor der Installation

Anrufaufzeichnungs-APIs verwenden ausschließlich serverCallId zum Initiieren der Aufzeichnung. Je nach Szenario gibt es mehrere Methoden, mit denen Sie serverCallId abrufen können:

Szenarien für die Anrufautomatisierung

Bei Verwendung der Anrufautomatisierung haben Sie zwei Optionen zum Abrufen der serverCallId:

Beim Aufbauen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf aufgebaut wurde. Im Anrufautomatisierungs-SDK erfahren Sie mehr über das Get CallConnected-Ereignis.
Sobald Sie den Aufruf beantworten oder einen Aufruf erstellt haben, wird serverCallId als Eigenschaft der AnswerCallResult- bzw. CreateCallResult-API-Antwort zurückgegeben.

SDK-Anrufszenarien

Bei Verwendung des Calling Client SDK können Sie die serverCallId abrufen, indem Sie die getServerCallId-Methode für den Anruf verwenden.

In diesem Beispiel erfahren Sie, wie Sie serverCallId über das Calling Client SDK abrufen.

Beginnen Sie mit einigen einfachen Schritten.

1. Erstellen eines Anrufautomatisierungsclients

APIs für die Anrufaufzeichnung sind Teil der Anrufautomatisierungsbibliotheken von Azure Communication Services. Sie müssen einen Anrufautomatisierungsclient erstellen.

Um einen Anrufautomatisierungsclient zu erstellen, verwenden Sie Ihre Communication Services-Verbindungszeichenfolge und übergeben sie an das CallAutomationClient-Objekt.

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

2. Starten der Aufzeichnung der Sitzung mit StartRecordingOptions mithilfe der `startWithResponse`-API

Verwenden Sie die Serveranruf-ID (serverCallId), die während der Initiierung des Aufrufs empfangen wurde.

Verwenden Sie RecordingContent, um den Aufzeichnungsinhaltstyp zu übergeben. Verwenden Sie AUDIO.
Verwenden Sie RecordingChannel, um den Aufzeichnungskanaltyp zu übergeben. Verwenden Sie MIXED oder UNMIXED.
Verwenden Sie RecordingFormat, um das Format der Aufzeichnung zu übergeben. Verwenden Sie 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. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

Starten Sie die Aufzeichnung mit Ihrem festgelegten Azure Blob Storage, um die aufgezeichnete Datei zu speichern, sobald die Aufzeichnung abgeschlossen ist.

        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. Starten der Aufzeichnung der Sitzung mit dem mithilfe der `StartAsync`-API aktivierten Pausenmodus

Hinweis

Aufzeichnungen müssen fortgesetzt werden, damit eine Aufzeichnungsdatei generiert wird.

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. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

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. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

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

Die startWithResponse-API-Antwort enthält die Aufzeichnungs-ID (recordingId) der Aufzeichnungssitzung.

3. Beenden der Aufzeichnung der Sitzung mithilfe der `stopWithResponse`-API

Verwenden Sie die recordingId, die als Antwort auf startWithResponse empfangen wurde.

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

4. Anhalten der Aufzeichnung der Sitzung mithilfe der `pauseWithResponse`-API

Verwenden Sie die recordingId, die als Antwort auf startWithResponse empfangen wurde.

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

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der `resumeWithResponse`-API

Verwenden Sie die recordingId, die als Antwort auf startWithResponse empfangen wurde.

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

6. Herunterladen der Aufzeichnungsdatei mit der `downloadToWithResponse`-API

Verwenden Sie einen Azure Event Grid Webhook oder eine andere ausgelöste Aktion, um Ihre Dienste zu benachrichtigen, wenn die aufgezeichneten Medien zum Download bereit stehen.

Eine Event Grid-Benachrichtigung (Microsoft.Communication.RecordingFileStatusUpdated) wird veröffentlicht, wenn eine Aufzeichnung abrufbereit ist. Dies ist in der Regel wenige Minuten nach Abschluss des Aufzeichnungsprozesses der Fall, also beispielsweise nach dem Ende der Besprechung oder nach dem Beenden der Aufzeichnung. Aufzeichnungsereignisbenachrichtigungen enthalten contentLocation und metadataLocation, mit denen sowohl aufgezeichnete Medien als auch eine Metadatendatei zur Aufzeichnung abgerufen werden können.

Der folgende Code ist ein Beispiel für ein Ereignisschema.

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

Verwenden Sie die downloadToWithResponse-Methode der CallRecording-Klasse, um die aufgezeichneten Medien herunterzuladen. Im Folgenden sind die unterstützten Parameter für die downloadToWithResponse-Methode angegeben:

contentLocation: Azure Communication Services-URL, unter der sich der Inhalt befindet.
destinationPath: Dateispeicherort
parallelDownloadOptions: Ein optionales ParallelDownloadOptions-Objekts zum Anpassen, wie das parallele Herunterladen funktioniert
overwrite: True, um die Datei zu überschreiben, sofern vorhanden.
context: Ein Kontext, der den Anforderungskontext darstellt.

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

Der Inhaltsspeicherort und die Dokument-IDs für die Aufzeichnungsdateien können für jedes recordingChunk aus den Feldern contentLocation bzw. documentId abgerufen werden.

7. Löschen von Aufzeichnungsinhalten mithilfe der `deleteWithResponse`-API

Verwenden Sie die deleteWithResponse-Methode der CallRecording-Klasse, um die aufgezeichneten Medien zu löschen. Unterstützte Parameter für die deleteWithResponse-Methode:

deleteLocation: Azure Communication Services-URL, unter der sich der zu löschende Inhalt befindet
context: Ein Kontext, der den Anforderungskontext darstellt.

Response<Void> deleteResponse = callAutomationClient.getCallRecording().deleteWithResponse(deleteLocation, context);

Der Löschspeicherort für die Aufzeichnung kann aus dem deleteLocation-Feld des Event Grid-Ereignisses abgerufen werden.

Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Voraussetzungen

Sie benötigen ein Azure-Konto mit einem aktiven Abonnement.
Stellen Sie eine Communication Services-Ressource bereit. Notieren Sie die Verbindungszeichenfolge Ihrer Ressource.
Abonnieren Sie Ereignisse über Azure Event Grid.
Python 3.7+.

Bevor Sie beginnen

Anrufaufzeichnungs-APIs verwenden ausschließlich serverCallId zum Initiieren der Aufzeichnung. Je nach Szenario gibt es mehrere Methoden, mit denen Sie serverCallId abrufen können:

Szenarien für die Anrufautomatisierung

Bei Verwendung der Anrufautomatisierung haben Sie zwei Optionen zum Abrufen der serverCallId:
1. Beim Aufbauen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf aufgebaut wurde. Im Anrufautomatisierungs-SDK erfahren Sie mehr über das Get CallConnected-Ereignis.
2. Sobald Sie den Aufruf beantworten oder einen Aufruf erstellt haben, wird serverCallId als Eigenschaft der AnswerCallResult- bzw. CreateCallResult-API-Antwort zurückgegeben.

SDK-Anrufszenarien

Bei Verwendung des Calling Client SDK können Sie die serverCallId abrufen, indem Sie die server_call_id-Variable für den Anruf verwenden. In diesem Beispiel erfahren Sie, wie Sie serverCallId über das Calling Client SDK abrufen.

Beginnen wir mit einigen einfachen Schritten!

1. Erstellen eines Anrufautomatisierungsclients

APIs für die Anrufaufzeichnung sind Teil der Anrufautomatisierungsbibliotheken von Azure Communication Services. Daher ist es erforderlich, einen Anrufautomatisierungsclient zu erstellen.

Um einen Anrufautomatisierungsclient zu erstellen, verwenden Sie Ihre Communication Services-Verbindungszeichenfolge und übergeben sie an das CallAutomationClient-Objekt.

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

2. Starten der Aufzeichnungssitzung mithilfe der API „start-recording“

Verwenden Sie die Serveranruf-ID (serverCallId), die während der Initiierung des Aufrufs empfangen wurde.

Verwenden Sie RecordingContent, um den Aufzeichnungsinhaltstyp zu übergeben. Verwenden Sie AUDIO.
Verwenden Sie RecordingChannel, um den Aufzeichnungskanaltyp zu übergeben. Verwenden Sie MIXED oder UNMIXED.
Verwenden Sie RecordingFormat, um das Format der Aufzeichnung zu übergeben. Verwenden Sie 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. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

Sie starten die Aufzeichnung mit Ihrer eigenen Azure Blob Storage-Instanz, die für die Speicherung der Aufzeichnungsdatei definiert wurde, nachdem die Aufzeichnung abgeschlossen wurde.

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. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

Hinweis

Aufzeichnungen müssen fortgesetzt werden, damit eine Aufzeichnungsdatei generiert wird.

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. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 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>",
            audio_channel_participant_ordering=[CommunicationUserIdentifier(id="<ACS_USER_MRI>")])

2.4. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

_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])

Die StartAsync-API-Antwort enthält die Aufzeichnungs-ID (recordingId) der Aufzeichnungssitzung.

3. Beenden der Aufzeichnungssitzung mithilfe der API „stop_recording“

Verwenden Sie die recording_id, die als Antwort auf start_recording empfangen wurde.

stop_recording = call_automation_client.stop_recording(recording_id = recording_id)

4. Anhalten der Aufzeichnungssitzung mithilfe der API „pause_recording“

Verwenden Sie die recording_id, die als Antwort auf start_recording empfangen wurde.

pause_recording = call_automation_client.pause_recording(recording_id = recording_id)

5. Fortsetzen der Aufzeichnungssitzung mithilfe der API „resume_recording“

Verwenden Sie die recording_id, die als Antwort auf start_recording empfangen wurde.

resume_recording = call_automation_client.resume_recording(recording_id = recording_id)

6. Herunterladen der Aufzeichnungsdatei mithilfe der API „download_recording“

Verwenden Sie einen Azure Event Grid Webhook oder eine andere ausgelöste Aktion, um Ihre Dienste zu benachrichtigen, wenn die aufgezeichneten Medien zum Download bereit stehen.

Eine Event Grid-Benachrichtigung (Microsoft.Communication.RecordingFileStatusUpdated) wird veröffentlicht, wenn eine Aufzeichnung abrufbereit ist. Dies ist in der Regel wenige Minuten nach Abschluss des Aufzeichnungsprozesses der Fall, also beispielsweise nach dem Ende der Besprechung oder nach dem Beenden der Aufzeichnung. Aufzeichnungsereignisbenachrichtigungen enthalten Werte für contentLocation und metadataLocation, mit denen sowohl aufgezeichnete Medien als auch eine Metadatendatei zur Aufzeichnung abgerufen werden können.

Der folgende Code ist ein Beispiel für ein Ereignisschema.

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

Verwenden Sie die download_recording-API zum Herunterladen der aufgezeichneten Medien.

response = recording_data = call_automation_client.download_recording(content_location)

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

Der downloadLocation für die Aufzeichnung kann über das contentLocation-Attribut von recordingChunk abgerufen werden. Verwenden Sie die download_recording-Methode, um den Inhalt in Bytes herunterzuladen.

7. Löschen von Aufzeichnungsinhalten mithilfe der API „delete_recording“

Verwenden Sie die delete_recording-API, um den Aufzeichnungsinhalt, z. B. aufgezeichnete Medien und Metadaten zu löschen.

response = call_automation_client.delete_recording(delete_location);

Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Voraussetzungen

Sie benötigen ein Azure-Konto mit einem aktiven Abonnement.
Stellen Sie eine Communication Services-Ressource bereit. Notieren Sie die Verbindungszeichenfolge Ihrer Ressource.
Abonnieren Sie Ereignisse über Azure Event Grid.
Node.js, Active LTS- und Maintenance LTS-Versionen (8.11.1 und 10.14.1 empfohlen)

Bevor Sie beginnen

Anrufaufzeichnungs-APIs verwenden ausschließlich serverCallId zum Initiieren der Aufzeichnung. Je nach Szenario gibt es mehrere Methoden, mit denen Sie serverCallId abrufen können:

Szenarien für die Anrufautomatisierung

Bei Verwendung der Anrufautomatisierung haben Sie zwei Optionen zum Abrufen der serverCallId:
1. Beim Aufbauen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf aufgebaut wurde. Hier erfahren Sie mehr zum Abrufen eines CallConnected-Ereignisses vom Anrufautomatisierungs-SDK.
2. Sobald Sie den Aufruf beantworten oder einen Aufruf erstellt haben, wird serverCallId als Eigenschaft der AnswerCallResult- bzw. CreateCallResult-API-Antwort zurückgegeben.

SDK-Anrufszenarien

Bei Verwendung des Calling Client SDK können Sie die serverCallId abrufen, indem Sie die getServerCallId-Methode für den Anruf verwenden.

Verwenden Sie dieses Beispiel, um mehr zum Abrufen einer serverCallId vom Calling Client SDK zu erfahren.

Beginnen wir mit einigen einfachen Schritten!

1. Erstellen eines Anrufautomatisierungsclients

APIs für die Anrufaufzeichnung sind Teil der Anrufautomatisierungsbibliotheken von Azure Communication Services. Daher ist es erforderlich, einen Anrufautomatisierungsclient zu erstellen.

Um einen Anrufautomatisierungsclient zu erstellen, verwenden Sie Ihre Communication Services-Verbindungszeichenfolge und übergeben sie an das CallAutomationClient-Objekt.

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

2. Starten der Aufzeichnungssitzung mit StartRecordingOptions mithilfe der „StartAsync“-API

Verwenden Sie die Serveranruf-ID (serverCallId), die während der Initiierung des Aufrufs empfangen wurde.

Verwenden Sie RecordingContent, um den Aufzeichnungsinhaltstyp zu übergeben. Verwenden Sie AUDIO.
Verwenden Sie RecordingChannel, um den Aufzeichnungskanaltyp zu übergeben. Verwenden Sie MIXED oder UNMIXED.
Verwenden Sie RecordingFormat, um das Format der Aufzeichnung zu übergeben. Verwenden Sie 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. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

Starten Sie die Aufzeichnung mit Ihrem festgelegten Azure Blob Storage, um die aufgezeichnete Datei zu speichern, sobald die Aufzeichnung abgeschlossen ist.

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. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

Hinweis

Aufzeichnungen müssen fortgesetzt werden, damit eine Aufzeichnungsdatei generiert wird.

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. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

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. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

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

Die StartAsync-API-Antwort enthält die Aufzeichnungs-ID (recordingId) der Aufzeichnungssitzung.

3. Beenden der Aufzeichnungssitzung mithilfe der „stop“-API

Verwenden Sie die recordingId, die als Antwort auf start empfangen wurde.

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

4. Anhalten der Aufzeichnungssitzung mithilfe der „pause“-API

Verwenden Sie die recordingId, die als Antwort auf start empfangen wurde.

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

5. Fortsetzen der Aufzeichnungssitzung mithilfe der „ResumeAsync“-API

Verwenden Sie die recordingId, die als Antwort auf start empfangen wurde.

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

6. Herunterladen der Aufzeichnungsdatei mithilfe der API „DownloadToAsync“

Verwenden Sie einen Azure Event Grid Webhook oder eine andere ausgelöste Aktion, um Ihre Dienste zu benachrichtigen, wenn die aufgezeichneten Medien zum Download bereit stehen.

Eine Event Grid-Benachrichtigung (Microsoft.Communication.RecordingFileStatusUpdated) wird veröffentlicht, wenn eine Aufzeichnung abrufbereit ist. Dies ist in der Regel wenige Minuten nach Abschluss des Aufzeichnungsprozesses der Fall, also beispielsweise nach dem Ende der Besprechung oder nach dem Beenden der Aufzeichnung. Aufzeichnungsereignisbenachrichtigungen enthalten Werte für contentLocation und metadataLocation, mit denen sowohl aufgezeichnete Medien als auch eine Metadatendatei zur Aufzeichnung abgerufen werden können.

Der folgende Code ist ein Beispiel für ein Ereignisschema.

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

Verwenden Sie die downloadToPath-API zum Herunterladen der aufgezeichneten Medien.

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

Der downloadLocation für die Aufzeichnung kann über das contentLocation-Attribut von recordingChunk abgerufen werden. Verwenden Sie die DownloadToAsync-Methode, um den Inhalt in einen bereitgestellten Dateinamen herunterzuladen.

7. Löschen von Aufzeichnungsinhalten mithilfe der „DeleteAsync“-API

Verwenden der delete-API zum Löschen des Aufzeichnungsinhalts (z. B. aufgezeichnete Medien, Metadaten)

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

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Artikeln:

Laden Sie unsere Anrufaufzeichnungsbeispiel-Apps für Java, Python und JavaScript herunter
Übersicht zur Anrufaufzeichnung
Informieren Sie sich ausführlicher über die Anrufautomatisierung.

Teilen über

Schnellstart: Anrufaufzeichnungs-API

Beispielcode

Voraussetzungen

Bevor Sie beginnen

Szenarien für die Anrufautomatisierung

SDK-Anrufszenarien

1. Erstellen eines Anrufautomatisierungsclients

2. Starten der Aufzeichnungssitzung mit StartRecordingOptions mithilfe der „StartAsync“-API

2.1. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

2.2. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

2.3. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

2.4. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

3. Beenden der Aufzeichnung der Sitzung mithilfe der StopAsync-API

4. Anhalten der Aufzeichnung der Sitzung mithilfe der PauseAsync-API

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der ResumeAsync-API

6. Herunterladen der Aufzeichnungsdatei mit der DownloadToAsync-API

7. Löschen von Aufzeichnungsinhalten mithilfe der DeleteAsync-API

Beispielcode

Voraussetzungen

Vor der Installation

Szenarien für die Anrufautomatisierung

SDK-Anrufszenarien

1. Erstellen eines Anrufautomatisierungsclients

2. Starten der Aufzeichnung der Sitzung mit StartRecordingOptions mithilfe der startWithResponse-API

2.1. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

2.2. Starten der Aufzeichnung der Sitzung mit dem mithilfe der StartAsync-API aktivierten Pausenmodus

2.3. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

2.4. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

3. Beenden der Aufzeichnung der Sitzung mithilfe der stopWithResponse-API

4. Anhalten der Aufzeichnung der Sitzung mithilfe der pauseWithResponse-API

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der resumeWithResponse-API

6. Herunterladen der Aufzeichnungsdatei mit der downloadToWithResponse-API

7. Löschen von Aufzeichnungsinhalten mithilfe der deleteWithResponse-API

Beispielcode

Voraussetzungen

Bevor Sie beginnen

Szenarien für die Anrufautomatisierung

SDK-Anrufszenarien

1. Erstellen eines Anrufautomatisierungsclients

2. Starten der Aufzeichnungssitzung mithilfe der API „start-recording“

2.1. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

2.2. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

2.3. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

2.4. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

3. Beenden der Aufzeichnungssitzung mithilfe der API „stop_recording“

4. Anhalten der Aufzeichnungssitzung mithilfe der API „pause_recording“

5. Fortsetzen der Aufzeichnungssitzung mithilfe der API „resume_recording“

6. Herunterladen der Aufzeichnungsdatei mithilfe der API „download_recording“

7. Löschen von Aufzeichnungsinhalten mithilfe der API „delete_recording“

Beispielcode

Voraussetzungen

Bevor Sie beginnen

Szenarien für die Anrufautomatisierung

SDK-Anrufszenarien

1. Erstellen eines Anrufautomatisierungsclients

2. Starten der Aufzeichnungssitzung mit StartRecordingOptions mithilfe der „StartAsync“-API

2.1. Starten der Aufzeichnung – Bring Your Own Azure Blob Store

2.2. Starten der Aufzeichnungssitzung mit der StartAsync-API mit aktiviertem Pausenmodus

2.3. Nur für „Unmixed“: Angeben eines Benutzers auf Kanal 0

2.4. Nur für „Unmixed“: Geben Sie einem Benutzers auf Kanal 0 an

3. Beenden der Aufzeichnungssitzung mithilfe der „stop“-API

4. Anhalten der Aufzeichnungssitzung mithilfe der „pause“-API

5. Fortsetzen der Aufzeichnungssitzung mithilfe der „ResumeAsync“-API

6. Herunterladen der Aufzeichnungsdatei mithilfe der API „DownloadToAsync“

7. Löschen von Aufzeichnungsinhalten mithilfe der „DeleteAsync“-API

Bereinigen von Ressourcen

Nächste Schritte

Feedback

Zusätzliche Ressourcen

3. Beenden der Aufzeichnung der Sitzung mithilfe der `StopAsync`-API

4. Anhalten der Aufzeichnung der Sitzung mithilfe der `PauseAsync`-API

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der `ResumeAsync`-API

6. Herunterladen der Aufzeichnungsdatei mit der `DownloadToAsync`-API

7. Löschen von Aufzeichnungsinhalten mithilfe der `DeleteAsync`-API

2. Starten der Aufzeichnung der Sitzung mit StartRecordingOptions mithilfe der `startWithResponse`-API

2.2. Starten der Aufzeichnung der Sitzung mit dem mithilfe der `StartAsync`-API aktivierten Pausenmodus

3. Beenden der Aufzeichnung der Sitzung mithilfe der `stopWithResponse`-API

4. Anhalten der Aufzeichnung der Sitzung mithilfe der `pauseWithResponse`-API

5. Fortsetzen der Aufzeichnung der Sitzung mithilfe der `resumeWithResponse`-API

6. Herunterladen der Aufzeichnungsdatei mit der `downloadToWithResponse`-API

7. Löschen von Aufzeichnungsinhalten mithilfe der `deleteWithResponse`-API