Merge pull request #231236 from dbasantes/main

Create bring-your-own-storage.md

Author: JamesJBarnett

.openpublishing.redirection.json

@@ -22455,6 +22455,11 @@
             "source_path": "articles/batch/high-availability-disaster-recovery.md",
             "redirect_URL": "/azure/reliability/reliability-batch",
             "redirect_document_id": false
+        },
+        {
+            "source_path_from_root": "/articles/communication-services/concepts/bring-your-own-storage.md",
+            "redirect_url": "/azure/communication-services/concepts/call-automation/call-recording/bring-your-own-storage",
+            "redirect_document_id": false
         }
 
     ]

articles/communication-services/concepts/bring-your-own-storage.md

@@ -0,0 +1,41 @@
+---
+title: Azure Communication Services BYOS overview
+titleSuffix: An Azure Communication Services concept document
+description: Learn about the Azure Communication Services BYOS.
+author: dbasantes
+manager: seaen
+services: azure-communication-services
+ms.author: dbasantes
+ms.date: 03/16/2023
+ms.topic: conceptual
+ms.service: azure-communication-services
+---
+
+# Bring your own storage (BYOS) overview
+
+[!INCLUDE [Private Preview Disclaimer](../../../../communication-services/includes/private-preview-include-section.md)]
+
+
+Bring Your Own Storage (BYOS) for Call Recording allows you to specify an Azure blob storage account for storing call recording files. BYOS enables businesses to store their data in a way that meets their compliance requirements and business needs. For example, end-users could customize their own rules and access to the data, enabling them to store or delete content whenever they need it. BYOS provides a simple and straightforward solution that eliminates the need for developers to invest time and resources in downloading and exporting files.
+
+The same Azure Communication Services Call Recording APIs are used to export recordings to your Azure Blob Storage Container. While starting recording for a call, specify the container path where the recording needs to be exported. Upon recording completion, Azure Communication Services automatically fetches and uploads your recording to your storage.
+
+![Diagram showing a call recording being automatically exported to storage container](../media/byos-concept.png)
+
+## Azure Managed Identities
+
+BYOS uses [Azure Managed Identities](../../../../active-directory/managed-identities-azure-resources/overview.md) to access user-owned resources securely. Azure Managed Identities provides an identity for the application to use when it needs to access Azure resources, eliminating the need for developers to manage credentials.
+
+
+## Known issues
+
+- Azure Communication Services will also store your files in a built-in storage for 48 hours even if the exporting with BYOS is successful.
+- Randomly, recording files are duplicated during the exporting process when using BYOS. Make sure you delete the duplicated file to avoid extra storage costs in your storage account.
+
+
+## Next steps
+For more information, see the following articles:
+- Learn more about BYOS, check out the [BYOS Quickstart](../../../quickstarts/call-automation/call-recording/bring-your-own-storage.md).
+- Learn more about Call recording, check out the [Call Recording Quickstart](../../../quickstarts/voice-video-calling/get-started-call-recording.md).
+- Learn more about [Call Automation](../../../quickstarts/call-automation/callflows-for-customer-interactions.md).
+

articles/communication-services/concepts/call-automation/call-recording/bring-your-own-storage.md

@@ -0,0 +1,110 @@
+---
+ms.author: dbasantes
+title: Azure Communication Services Call Recording Bring Your Own Storage
+titleSuffix: An Azure Communication Services document
+description: Private Preview quickstart for Bring your own storage
+author: dbasantes
+services: azure-communication-services
+ms.date: 03/17/2023
+ms.topic: quickstart
+ms.service: azure-communication-services
+ms.subservice: calling
+zone_pivot_groups: acs-csharp-java
+ms.custom: mode-api
+---
+# Call recording: Bring your own storage quickstart
+
+[!INCLUDE [Private Preview](../../../includes/private-preview-include-section.md)]
+
+This quickstart gets you started with BYOS (Bring your own storage) for Call Recording. To start using BYOS, make sure you're familiar with the [Call Recording APIs](../../voice-video-calling/get-started-call-recording.md).
+
+## Pre-requisite: Setting up Managed Identity and RBAC role assignments
+
+### 1. Enable system assigned managed identity for Azure Communication Services
+
+![Diagram showing a communication service resource with managed identity disabled](../media/byos-managed-identity-1.png)
+
+1. Open your Azure Communication Services resource. Navigate to *Identity* on the left.
+2. System Assigned Managed Identity is disabled by default. Enable it and click of *Save*
+3. Once completed, you're able to see the Object principal ID of the newly created identity.
+
+![Diagram showing a communication service resource with managed identity enabled](../media/byos-managed-identity-2.png)
+
+4. Now that identity has been successfully created, click on *Azure role assignments* to start adding role assignments.
+
+### 2. Add role assignment
+
+1. Click on *"Add role assignment"*
+
+![Diagram showing a communication service resource managed identity adding role assignment](../media/role-assignment-1.png)
+
+2. On the *"Add role assignment"* panel, select the following values
+     1. Scope: **Storage**
+     2. Subscription: **Choose your subscription**
+     3. Resource: **Choose your storage account**
+     4. Role: **Azure Communication Services needs *"Storage Blob Data Contributor"* to be able to write to your storage account.**
+    
+![Diagram showing a communication service resource managed identity adding role assignment details](../media/role-assignment-2.png)
+
+3. Click on *"Save"*.
+4. Once completed, you see the newly added role assignment in the *"Azure role assignment"* window.
+
+![Diagram showing a communication service resource managed identity role assignment success](../media/role-assignment-3.png)
+
+## Start recording session with external storage specified
+
+Use the server call ID received during initiation of the call.
+
+::: zone pivot="programming-language-csharp"
+[!INCLUDE [Test Call Recording BYOS with C#](../includes/recording-byos-private-csharp.md)]
+::: zone-end
+
+::: zone pivot="programming-language-java"
+[!INCLUDE [Test Call Recording BYOS with Java](../includes/recording-byos-private-java.md)]
+::: zone-end
+
+### Notification on successful export
+
+Use an [Azure Event Grid](../../../../event-grid/overview.md) web hook, or other triggered action, to notify your services when the recorded media is ready and have been exported to the external storage location.
+
+Refer to this example of the event schema.
+
+```JSON
+{
+    "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": {
+        "storageType": "string", // acsstorage, blobstorage etc.
+        "recordingId": "string", // unique id for recording
+        "recordingStorageInfo": {
+            "recordingChunks": [
+                {
+                    "documentId": "string", // Document id for 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
+}
+```
+
+## Next steps
+
+For more information, see the following articles:
+
+- Download our [Java](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/ServerRecording) and [.NET](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/ServerRecording) call recording sample apps 
+- Learn more about [Call Recording](../../../concepts/voice-video-calling/call-recording.md)
+- Learn more about [Call Automation](../../../concepts/call-automation/call-automation.md)
+

articles/communication-services/concepts/call-automation/media/byos-concept.png

@@ -0,0 +1,25 @@
+---
+title: include file
+description: C# call recording bring your own storage
+services: azure-communication-services
+author: dbasantes
+ms.service: azure-communication-services
+ms.subservice: azure-communication-services
+ms.date: 03/17/2023
+ms.topic: include
+ms.custom: include file
+ms.author: dbasantes
+---
+
+### Using Azure blob storage for external storage
+
+```csharp
+StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
+{
+    //...
+    ExternalStorage = new BlobStorage(new Uri("<Insert Container / Blob Uri>"))
+};
+               
+Response<RecordingStateResult> startRecordingWithResponse = await callAutomationClient.GetCallRecording()
+        .StartRecordingAsync(options: recordingOptions);
+```

articles/communication-services/quickstarts/call-automation/call-recording/bring-your-own-storage.md

@@ -0,0 +1,22 @@
+---
+title: include file
+description: java call recording bring your own storage
+services: azure-communication-services
+author: dbasantes
+ms.service: azure-communication-services
+ms.subservice: azure-communication-services
+ms.date: 03/17/2023
+ms.topic: include
+ms.custom: include file
+ms.author: dbasantes
+---
+
+## Using Azure blob storage for external storage
+
+```java
+StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
+                .setExternalStorage(new BlobStorage("<Insert Container / Blob Uri>"));
+
+Response<StartCallRecordingResult> response = callAutomationClient.getCallRecording()
+.startRecordingWithResponse(recordingOptions, null);
+```