Add ApiProperties support for Cognitive Services (#12870)

* Add ApiProperties support

* Change ApiProperties to singular in cmdlet name and parameter

* Update NewAzureCognitiveServicesAccountApiProperty.cs

Remove `SupportsShouldProcess = true`

* Override signature issue

src/CognitiveServices/CognitiveServices.Test/ScenarioTests/CognitiveServicesAccountTests.cs

@@ -226,5 +226,12 @@ public void TestCapabilities()
         {
             TestController.NewInstance.RunPsTest(traceInterceptor, "Test-Capabilities");
         }
+
+        [Fact]
+        [Trait(Category.AcceptanceType, Category.CheckIn)]
+        public void TestApiProperties()
+        {
+            TestController.NewInstance.RunPsTest(traceInterceptor, "Test-ApiProperties");
+        }
     }
 }

src/CognitiveServices/CognitiveServices.Test/ScenarioTests/CognitiveServicesAccountTests.ps1

@@ -1303,4 +1303,41 @@ function Test-Capabilities
         # Cleanup
         Clean-ResourceGroup $rgname
     }
+}
+
+<#
+.SYNOPSIS
+Test ApiProperties
+#>
+function Test-ApiProperties
+{
+    # Setup
+    $rgname = Get-CognitiveServicesManagementTestResourceName;
+
+    try
+    {
+        # Test
+        $accountname = 'csa' + $rgname;
+        $skuname = 'S0';
+        $accounttype = 'QnAMaker';
+        $loc = "West US";
+
+        New-AzResourceGroup -Name $rgname -Location $loc;
+        $apiProperties = New-AzCognitiveServicesAccountApiProperty
+        $apiProperties.QnaRuntimeEndpoint = "https://sdk-test-qna-maker.azurewebsites.net"
+        $createdAccount = New-AzCognitiveServicesAccount -ResourceGroupName $rgname -Name $accountname -Type $accounttype -SkuName $skuname -Location $loc -CustomSubdomainName $accountname -ApiProperty $apiProperties -Force;
+        Assert-NotNull $createdAccount;
+        Assert-True {$createdAccount.ApiProperties.QnaRuntimeEndpoint -eq "https://sdk-test-qna-maker.azurewebsites.net"}
+
+        $apiProperties.QnaRuntimeEndpoint = "https://qnamaker.azurewebsites.net"
+
+        $updatedAccount = Set-AzCognitiveServicesAccount -ResourceGroupName $rgname -Name $accountname -ApiProperty $apiProperties -Force;
+        Assert-NotNull $updatedAccount;
+        Assert-True {$updatedAccount.ApiProperties.QnaRuntimeEndpoint -eq "https://qnamaker.azurewebsites.net"}
+    }
+    finally
+    {
+        # Cleanup
+        Clean-ResourceGroup $rgname
+    }
 }

src/CognitiveServices/CognitiveServices/Az.CognitiveServices.psd1

@@ -86,7 +86,8 @@ CmdletsToExport = 'Get-AzCognitiveServicesAccount',
                'Get-AzCognitiveServicesAccountNetworkRuleSet', 
                'Update-AzCognitiveServicesAccountNetworkRuleSet', 
                'Add-AzCognitiveServicesAccountNetworkRule', 
-               'Remove-AzCognitiveServicesAccountNetworkRule'
+               'Remove-AzCognitiveServicesAccountNetworkRule', 
+               'New-AzCognitiveServicesAccountApiProperty'
 
 # Variables to export from this module
 # VariablesToExport = @()

src/CognitiveServices/CognitiveServices/ChangeLog.md

@@ -18,6 +18,8 @@
         - Additional information about change #1
 -->
 ## Upcoming Release
+* Add `New-AzCognitiveServicesAccountApiProperty` command.
+* Support "ApiProperty" parameter for `New-AzCognitiveServicesAccount` and `Set-AzCognitiveServicesAccount`
 
 ## Version 1.6.0
 * Showed additional legal terms for certain APIs.

src/CognitiveServices/CognitiveServices/CognitiveServicesAccount/NewAzureCognitiveServicesAccount.cs

@@ -161,6 +161,11 @@ public string KeyVaultUri
         [ValidateSet("Enabled", "Disabled", IgnoreCase = true)]
         public string PublicNetworkAccess { get; set; }
 
+        [Parameter(
+            Mandatory = false,
+            HelpMessage = "The ApiProperties of Cognitive Services Account. Required by specific account types.")]
+        public CognitiveServicesAccountApiProperties ApiProperty { get; set; }
+
         [Parameter(Mandatory = false, HelpMessage = "Don't ask for confirmation.")]
         public SwitchParameter Force { get; set; }
 
@@ -181,6 +186,11 @@ public override void ExecuteCmdlet()
                     properties.NetworkAcls = NetworkRuleSet.ToNetworkRuleSet();
                 }
 
+                if (ApiProperty != null)
+                {
+                    properties.ApiProperties = ApiProperty;
+                }
+
                 CognitiveServicesAccount createParameters = new CognitiveServicesAccount()
                 {
                     Location = Location,
@@ -270,10 +280,19 @@ public override void ExecuteCmdlet()
                                         Name,
                                         createParameters);
                     }
+                    catch (ErrorException ex)
+                    {
+                        // If the Exception is ErrorException, clone the exception with modified message.
+                        var newEx = new ErrorException($"Failed to create Cognitive Services account. {ex.Message}", ex);
+                        newEx.Body = ex.Body;
+                        newEx.Request = ex.Request;
+                        newEx.Response = ex.Response;
+                        throw newEx;
+                    }
                     catch (Exception ex)
                     {
                         // Give users a specific message says `Failed to create Cognitive Services account.`
-                        // Details should able be found in the exception.
+                        // Details should able be found in the inner exception.
                         throw new Exception("Failed to create Cognitive Services account.", ex);
                     }
 

src/CognitiveServices/CognitiveServices/CognitiveServicesAccount/NewAzureCognitiveServicesAccountApiProperty.cs

@@ -0,0 +1,34 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+using Microsoft.Azure.Management.CognitiveServices.Models;
+using System.Management.Automation;
+using CognitiveServicesModels = Microsoft.Azure.Management.CognitiveServices.Models;
+
+namespace Microsoft.Azure.Commands.Management.CognitiveServices
+{
+    /// <summary>
+    /// Generate Cognitive Services Account ApiProperties class
+    /// </summary>
+    [Cmdlet("New", ResourceManager.Common.AzureRMConstants.AzureRMPrefix + "CognitiveServicesAccountApiProperty"), OutputType(typeof(CognitiveServicesModels.CognitiveServicesAccountApiProperties))]
+    public class NewAzureCognitiveServicesAccountApiPropertyCommand : CognitiveServicesAccountBaseCmdlet
+    {
+        public override void ExecuteCmdlet()
+        {
+            base.ExecuteCmdlet();
+
+            WriteObject(new CognitiveServicesAccountApiProperties());
+        }
+    }
+}

src/CognitiveServices/CognitiveServices/CognitiveServicesAccount/SetAzureCognitiveServicesAccount.cs

@@ -145,6 +145,11 @@ public string KeyVaultUri
         [ValidateSet("Enabled", "Disabled", IgnoreCase = true)]
         public string PublicNetworkAccess { get; set; }
 
+        [Parameter(
+            Mandatory = false,
+            HelpMessage = "The ApiProperties of Cognitive Services Account. Required by specific account types.")]
+        public CognitiveServicesAccountApiProperties ApiProperty { get; set; }
+
         [Parameter(Mandatory = false, HelpMessage = "Don't ask for confirmation.")]
         public SwitchParameter Force { get; set; }
 
@@ -164,6 +169,11 @@ public override void ExecuteCmdlet()
                 hasPropertiesChange = true;
                 properties.NetworkAcls = NetworkRuleSet.ToNetworkRuleSet();
             }
+            if (ApiProperty != null)
+            {
+                hasPropertiesChange = true;
+                properties.ApiProperties = ApiProperty;
+            }
 
             Sku sku = null;
             if (!string.IsNullOrWhiteSpace(this.SkuName))

src/CognitiveServices/CognitiveServices/CognitiveServicesAccount/UpdateAzureCognitiveServicesAccountNetworkRuleSet.cs

@@ -99,7 +99,6 @@ public PSVirtualNetworkRule[] VirtualNetworkRule
         private bool isIpRuleSet = false;
         private bool isNetworkRuleSet = false;
 
-
         public override void ExecuteCmdlet()
         {
             base.ExecuteCmdlet();

src/CognitiveServices/CognitiveServices/help/New-AzCognitiveServicesAccount.md

@@ -18,17 +18,19 @@ Creates a Cognitive Services account.
 New-AzCognitiveServicesAccount [-ResourceGroupName] <String> [-Name] <String> [-Type] <String>
  [-SkuName] <String> [-Location] <String> [-Tag <Hashtable[]>] [-CustomSubdomainName <String>]
  [-AssignIdentity] [-StorageAccountId <String[]>] [-CognitiveServicesEncryption]
- [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>] [-Force]
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>]
+ [-ApiProperty <CognitiveServicesAccountApiProperties>] [-Force] [-DefaultProfile <IAzureContextContainer>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### KeyVaultEncryption
 ```
 New-AzCognitiveServicesAccount [-ResourceGroupName] <String> [-Name] <String> [-Type] <String>
  [-SkuName] <String> [-Location] <String> [-Tag <Hashtable[]>] [-CustomSubdomainName <String>]
  [-AssignIdentity] [-StorageAccountId <String[]>] [-KeyVaultEncryption] -KeyName <String> -KeyVersion <String>
- -KeyVaultUri <String> [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>] [-Force]
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ -KeyVaultUri <String> [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>]
+ [-ApiProperty <CognitiveServicesAccountApiProperties>] [-Force] [-DefaultProfile <IAzureContextContainer>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -59,6 +61,21 @@ Tags              :
 
 ## PARAMETERS
 
+### -ApiProperty
+The ApiProperties of Cognitive Services Account. Required by specific account types.
+
+```yaml
+Type: Microsoft.Azure.Management.CognitiveServices.Models.CognitiveServicesAccountApiProperties
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -AssignIdentity
 Generate and assign a new Cognitive Services Account Identity for this storage account for use with key management services like Azure KeyVault.
 

src/CognitiveServices/CognitiveServices/help/New-AzCognitiveServicesAccountApiProperty.md

@@ -0,0 +1,98 @@
+---
+external help file: Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll-Help.xml
+Module Name: Az.CognitiveServices
+online version: https://docs.microsoft.com/en-us/powershell/module/az.cognitiveservices/new-azcognitiveservicesaccountapiproperty
+schema: 2.0.0
+---
+
+# New-AzCognitiveServicesAccountApiProperty
+
+## SYNOPSIS
+Generate a new instance of Cognitive Services Account ApiProperties
+
+## SYNTAX
+
+```
+New-AzCognitiveServicesAccountApiProperty [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+Generate a new instance of Cognitive Services Account ApiProperties.
+ApiProperties can be used when creating a new account or updating an existing account.
+ApiProperties is required by certain account types.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+PS C:\> $apiProperties = New-AzCognitiveServicesAccountApiProperty
+PS C:\> $apiProperties.QnaRuntimeEndpoint = "https://qnamaker.azurewebsites.net"
+PS C:\> New-AzCognitiveServicesAccount -ResourceGroupName cognitive-services-resource-group -name qnamaker -Type QnAMaker -SkuName S0 -Locatio WestUS -ApiProperty $apiProperties
+```
+
+Above example will create an QnAMaker account, with API property "QnaRuntimeEndpoint".
+
+
+## PARAMETERS
+
+### -DefaultProfile
+The credentials, account, tenant, and subscription used for communication with Azure.
+
+```yaml
+Type: IAzureContextContainer
+Parameter Sets: (All)
+Aliases: AzContext, AzureRmContext, AzureCredential
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Confirm
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+### Microsoft.Azure.Management.CognitiveServices.Models.CognitiveServicesAccountApiProperties
+
+## NOTES
+
+## RELATED LINKS

src/CognitiveServices/CognitiveServices/help/Set-AzCognitiveServicesAccount.md

@@ -18,17 +18,18 @@ Modifies an account.
 Set-AzCognitiveServicesAccount [-ResourceGroupName] <String> [-Name] <String> [-SkuName <String>]
  [-Tag <Hashtable[]>] [-CustomSubdomainName <String>] [-AssignIdentity] [-IdentityType <IdentityType>]
  [-StorageAccountId <String[]>] [-CognitiveServicesEncryption] [-NetworkRuleSet <PSNetworkRuleSet>]
- [-PublicNetworkAccess <String>] [-Force] [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-PublicNetworkAccess <String>] [-ApiProperty <CognitiveServicesAccountApiProperties>] [-Force]
+ [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### KeyVaultEncryption
 ```
 Set-AzCognitiveServicesAccount [-ResourceGroupName] <String> [-Name] <String> [-SkuName <String>]
  [-Tag <Hashtable[]>] [-CustomSubdomainName <String>] [-AssignIdentity] [-IdentityType <IdentityType>]
  [-StorageAccountId <String[]>] [-KeyVaultEncryption] -KeyName <String> -KeyVersion <String>
- -KeyVaultUri <String> [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>] [-Force]
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ -KeyVaultUri <String> [-NetworkRuleSet <PSNetworkRuleSet>] [-PublicNetworkAccess <String>]
+ [-ApiProperty <CognitiveServicesAccountApiProperties>] [-Force] [-DefaultProfile <IAzureContextContainer>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -57,6 +58,21 @@ Tags              :
 
 ## PARAMETERS
 
+### -ApiProperty
+The ApiProperties of Cognitive Services Account. Required by specific account types.
+
+```yaml
+Type: Microsoft.Azure.Management.CognitiveServices.Models.CognitiveServicesAccountApiProperties
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -AssignIdentity
 Generate and assign a new Cognitive Services Account Identity for this storage account for use with key management services like Azure KeyVault.
 

tools/StaticAnalysis/Exceptions/Az.CognitiveServices/SignatureIssues.csv

@@ -5,4 +5,5 @@
 "Microsoft.Azure.PowerShell.Cmdlets.Management.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.RemoveAzureCognitiveServicesAccountCommand","Remove-AzCognitiveServicesAccount","1","8600","Cmdlet 'Remove-AzCognitiveServicesAccount' has no defined output type.","Add an OutputType attribute that declares the type of the object(s) returned by this cmdlet. If this cmdlet returns no output, please set the output type to 'bool' and make sure to implement the 'PassThru' parameter."
 "Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.NewAzureCognitiveServicesAccountCommand","New-AzCognitiveServicesAccount","1","8420","Parameter set 'KeyVaultEncryption' of cmdlet 'New-AzCognitiveServicesAccount' contains at least one parameter with a position larger than four, which is discouraged.","Limit the number of positional parameters in a single parameter set to four or fewer."
 "Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.NewAzureCognitiveServicesAccountCommand","New-AzCognitiveServicesAccount","1","8510","Cmdlet 'New-AzCognitiveServicesAccount' has multiple parameter sets, but no defined default parameter set.","Define a default parameter set in the cmdlet attribute."
-"Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.NewAzureCognitiveServicesAccountCommand","New-AzCognitiveServicesAccount","1","8420","Parameter set 'CognitiveServicesEncryption' of cmdlet 'New-AzCognitiveServicesAccount' contains at least one parameter with a position larger than four, which is discouraged.","Limit the number of positional parameters in a single parameter set to four or fewer."
+"Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.NewAzureCognitiveServicesAccountCommand","New-AzCognitiveServicesAccount","1","8420","Parameter set 'CognitiveServicesEncryption' of cmdlet 'New-AzCognitiveServicesAccount' contains at least one parameter with a position larger than four, which is discouraged.","Limit the number of positional parameters in a single parameter set to four or fewer."
+"Microsoft.Azure.PowerShell.Cmdlets.CognitiveServices.dll","Microsoft.Azure.Commands.Management.CognitiveServices.NewAzureCognitiveServicesAccountApiPropertyCommand","New-AzCognitiveServicesAccountApiProperty","1","8100","New-AzCognitiveServicesAccountApiProperty Does not support ShouldProcess but the cmdlet verb New indicates that it should.","Determine if the cmdlet should implement ShouldProcess and if so determine if it should implement Force / ShouldContinue"