Share via

Schnellstart zur Anrufaufzeichnung

  • Artikel

In diesem Schnellstart erfahren Sie mehr über die ersten Schritte mit der Anrufaufzeichnung für Sprach- und Videoanrufe. 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 Anruffunktionen für Endbenutzer 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:
    1. Beim Erstellen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf eingerichtet 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 getServerCallId-Methode 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.

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.

  • „RecordingContent“ wird zum Übergeben des Inhaltstyp der Aufzeichnung verwendet. Verwenden von Audiodateien
  • „RecordingChannel“ wird zum Übergeben des Kanaltyps der Aufzeichnung verwendet. Verwenden Sie „mixed“ oder „unmixed“.
  • „RecordingFormat“ wird zum Übergeben des Formats der Aufzeichnung verwendet. 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

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.

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. 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 Aufzeichnungssitzung mithilfe der „StopAsync“-API

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf StartAsync empfangen wurde.

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

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

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf StartAsync empfangen wurde.

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

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

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf StartAsync empfangen wurde.

var resumeRecording = await callAutomationClient.GetCallRecording().ResumeAsync(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.

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

Der downloadLocation für die Aufzeichnung kann über das contentLocation-Attribut von recordingChunk abgerufen werden. DownloadToAsync-Methode: Herunterladen des Inhalts in den angegebenen Dateinamen.

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

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

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

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 Erstellen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf eingerichtet 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 getServerCallId-Methode 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 Ihrem CallAutomationClient-Objekt.

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

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

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

  • „RecordingContent“ wird zum Übergeben des Inhaltstyp der Aufzeichnung verwendet. Verwenden von AUDIO
  • „RecordingChannel“ wird zum Übergeben des Kanaltyps der Aufzeichnung verwendet. Verwenden Sie MIXED oder UNMIXED.
  • „RecordingFormat“ wird zum Übergeben des Formats der Aufzeichnung verwendet. 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

Sie starten die Aufzeichnungssitzung mit Ihrer eigenen Azure Blob Storage-Instanz, in der die Aufzeichnungsdatei nach Abschluss der Aufzeichnung gespeichert wird.

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

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

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 Aufzeichnungssitzung mithilfe der „stopWithResponse“-API

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf startWithResponse empfangen wurde.

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

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

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf startWithResponse empfangen wurde.

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

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

Verwenden Sie die Aufzeichnungs-ID (recordingId), die als Antwort auf startWithResponse empfangen wurde.

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

6. Herunterladen der Aufzeichnungsdatei mithilfe der API „downloadToWithResponse“

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.

Im Folgenden finden Sie ein 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 downloadToWithResponse-Methode der CallRecording-Klasse zum Herunterladen der aufgezeichneten Medien. 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-Objekt, um die Funktionsweise des parallelen Downloads zu ändern.
  • 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 zum Löschen der aufgezeichneten Medien. Im Folgenden sind die unterstützten Parameter für die deleteWithResponse-Methode angegeben:

  • 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 Erstellen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf eingerichtet 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 Ihrem 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.

  • „RecordingContent“ wird zum Übergeben des Inhaltstyp der Aufzeichnung verwendet. Verwenden von Audiodateien
  • „RecordingChannel“ wird zum Übergeben des Kanaltyps der Aufzeichnung verwendet. Verwenden Sie „mixed“ oder „unmixed“.
  • „RecordingFormat“ wird zum Übergeben des Formats der Aufzeichnung verwendet. 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

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

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 Aufzeichnungs-ID (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 Aufzeichnungs-ID (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 Aufzeichnungs-ID (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.

Im Folgenden finden Sie ein 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 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. download_recording-Methode zum Herunterladen des Inhalts in Bytes.

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

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

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 Erstellen eines Anrufs wird serverCallId als Eigenschaft des CallConnected-Ereignisses zurückgegeben, nachdem ein Anruf eingerichtet 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 getServerCallId-Methode 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 Ihrem 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.

  • „RecordingContent“ wird zum Übergeben des Inhaltstyp der Aufzeichnung verwendet. Verwenden von Audiodateien
  • „RecordingChannel“ wird zum Übergeben des Kanaltyps der Aufzeichnung verwendet. Verwenden Sie „mixed“ oder „unmixed“.
  • „RecordingFormat“ wird zum Übergeben des Formats der Aufzeichnung verwendet. 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

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.

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

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

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 Aufzeichnungs-ID (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 Aufzeichnungs-ID (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 Aufzeichnungs-ID (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.

Im Folgenden finden Sie ein 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 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. DownloadToAsync-Methode: Herunterladen des Inhalts in den angegebenen Dateinamen.

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: