Merge pull request #249692 from mgreenegit/aiservice-powershell-0

add powershell to quickstarts

Author: ttorble

articles/ai-services/authentication.md

@@ -3,13 +3,13 @@ title: Authentication in Azure AI services
 titleSuffix: Azure AI services
 description: "There are three ways to authenticate a request to an Azure AI services resource: a resource key, a bearer token, or a multi-service subscription. In this article, you'll learn about each method, and how to make a request."
 services: cognitive-services
-author: PatrickFarley
+author: mgreenegit
 manager: nitinme
 ms.service: cognitive-services
 ms.custom: devx-track-azurepowershell
 ms.topic: how-to
-ms.date: 09/01/2022
-ms.author: pafarley
+ms.date: 08/30/2023
+ms.author: migreene
 ---
 
 # Authenticate requests to Azure AI services

articles/ai-services/includes/quickstarts/environment-variables.md

@@ -8,23 +8,39 @@ ms.author: aahi
 
 ## Configure an environment variable for authentication
 
-Your application must be authenticated to access Azure AI services resources. For production, use a secure way of storing and accessing your credentials. For example, after you have a key for your resource, write it to a new environment variable on the local machine running the application.
+Your application must be authenticated to access Azure AI services resources. To set the environment variable for your resource key, open a console window, and follow the instructions for your operating system and development environment. To set the `COGNITIVE_SERVICE_KEY` environment variable, replace `your-key` with one of the keys for your resource.
+
+For production, use a secure way of storing and accessing your credentials, such as a password-protected secret vault. For test, writing to an environment variable is standard practice, but keep in mind that environment variables are stored in clear text on the local machine.
 
 > [!TIP]
 > Don't include the key directly in your code, and never post it publicly. See the Azure AI services [security](../../security-features.md) article for more authentication options like [Azure Key Vault](../../use-key-vault.md). 
 
-To set the environment variable for your resource key, open a console window, and follow the instructions for your operating system and development environment. To set the `COGNITIVE_SERVICE_KEY` environment variable, replace `your-key` with one of the keys for your resource.
+
 
 #### [Windows](#tab/windows)
 
+PowerShell includes an extensible solution,
+[Secret Management](/powershell/module/microsoft.powershell.secretmanagement),
+for storing secure strings in platforms such as [Secret Store](/powershell/module/microsoft.powershell.secretstore) or [Azure KeyVault](/powershell/utility-modules/secretmanagement/how-to/using-azure-keyvault).
+
+To set up a secret store to host secure strings, see the article
+[Getting started using secret store](/powershell/utility-modules/secretmanagement/get-started/using-secretstore). Then use the following examples to store your api keys.
+
+```powershell
+Set-Secret -Name COGNITIVE_SERVICE_KEY -value your-key
+```
+
+For test environments, you can either use PowerShell's `$Env:` syntax to set an environment variable for only the current session, or the `setx` command to retain the variable across sessions. Remember that these values are stored in clear text in Windows registry keys.
+
+```powershell
+$Env:COGNITIVE_SERVICE_KEY = your-key
+```
+
 ```console
 setx COGNITIVE_SERVICE_KEY your-key
 ```
 
-> [!NOTE]
-> If you only need to access the environment variable in the current running console, you can set the environment variable with `set` instead of `setx`.
-
-After you add the environment variable, you may need to restart any running consoles or other programs that will need to read the environment variable. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example. 
+After you add the environment variable using `setx`, you may need to restart any running consoles or other programs that will need to read the environment variable. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example. 
 
 #### [Linux](#tab/linux)
 

articles/ai-services/includes/quickstarts/management-azpowershell.md

@@ -0,0 +1,122 @@
+---
+title: Create an Azure AI services resource using Azure PowerShell
+titleSuffix: Azure AI services
+description: Get started with Azure AI services by using Azure PowerShell commands to create and subscribe to a resource.
+services: cognitive-services
+author: mgreenegit
+manager: nitinme
+ms.service: cognitive-services
+keywords: Azure AI services, cognitive intelligence, cognitive solutions, ai services
+ms.topic: include
+ms.date: 08/29/2022
+ms.author: migreene
+ms.custom: mode-api, devx-track-azurepowershell
+ms.devlang: azurepowershell
+---
+
+Use this quickstart to create an Azure AI services resource using [Azure PowerShell](/powershell/azure/install-azure-powershell) commands. After you create the resource, use the keys and endpoint generated for you to authenticate your applications.
+
+Azure AI services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. They are available through REST APIs and client library SDKs in popular development languages. Azure AI services enables developers to easily add cognitive features into their applications with cognitive solutions that can see, hear, speak, and analyze.
+
+## Prerequisites
+
+* A valid Azure subscription - [Create one](https://azure.microsoft.com/free/cognitive-services) for free.
+* [Azure PowerShell](/powershell/azure/install-azure-powershell)
+* [!INCLUDE [contributor-requirement](contributor-requirement.md)]
+* [!INCLUDE [terms-azure-portal](terms-azure-portal.md)]
+
+## Install Azure PowerShell and sign in
+
+Install [Azure PowerShell](/powershell/azure/install-azure-powershell). To sign in, run the [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) command:
+
+```azurepowershell
+Connect-AzAccount
+```
+
+You can also use the green **Try It** button to run these commands in your browser.
+
+## Create a new Azure AI services resource group
+
+Before you create an Azure AI services resource, you must have an Azure resource group to contain the resource. When you create a new resource, you can either create a new resource group, or use an existing one. This article shows how to create a new resource group.
+
+### Choose your resource group location
+
+To create a resource, you'll need one of the Azure locations available for your subscription. You can retrieve a list of available locations with the [Get-AzLocation](/powershell/module/az.resources/get-azlocation) command. Most Azure AI services can be accessed from several locations. Choose the one closest to you, or see which locations are available for the service.
+
+> [!IMPORTANT]
+> * Remember your Azure location, as you will need it when calling the Azure AI services resources.
+> * The availability of some Azure AI services can vary by region. For more information, see [Azure products by region](https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services).
+
+```azurepowershell-interactive
+Get-AzLocation | Select-Object -Property Location, DisplayName
+```
+
+After you have your Azure location, create a new resource group in Azure PowerShell using the [New-AzResourceGroup](/powershell/module/az.resources/new-azresourcegroup) command. In the example below, replace the Azure location `westus2` with one of the Azure locations available for your subscription.
+
+```azurepowershell-interactive
+New-AzResourceGroup -Name ai-services-resource-group -Location westus2
+```
+
+## Create an Azure AI services resource
+
+### Choose a service and pricing tier
+
+When you create a new resource, you'll need to know the kind of service you want to use, along with the [pricing tier](https://azure.microsoft.com/pricing/details/cognitive-services/) (or SKU) you want. You'll use this and other information as parameters when you create the resource.
+
+[!INCLUDE [SKUs and pricing](sku-pricing.md)]
+
+You can find a list of available Azure AI services "kinds" with the [Get-AzCognitiveServicesAccountType](/powershell/module/az.cognitiveservices/get-azcognitiveservicesaccounttype) command:
+
+```azurepowershell-interactive
+Get-AzCognitiveServicesAccountType
+```
+
+### Add a new resource to your resource group
+
+To create and subscribe to a new Azure AI services resource, use the [New-AzCognitiveServicesAccount](/powershell/module/az.cognitiveservices/new-azcognitiveservicesaccount) command. This command adds a new billable resource to the resource group you created earlier. When you create your new resource, you'll need to know the "kind" of service you want to use, along with its pricing tier (or SKU) and an Azure location:
+
+You can create a Standard S0 multi-service resource named `multi-service-resource` with the command below.
+
+```azurepowershell-interactive
+New-AzCognitiveServicesAccount -ResourceGroupName ai-services-resource-group -Name multi-service-resource -Type CognitiveServices -SkuName F0 -Location westus2
+```
+
+> [!Tip]
+> If your subscription doesn't allow you to create an Azure AI services resource, you may need to enable the privilege of that [Azure resource provider](../../../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider) using the [Azure portal](../../../azure-resource-manager/management/resource-providers-and-types.md#azure-portal), an [Azure PowerShell command](../../../azure-resource-manager/management/resource-providers-and-types.md#azure-powershell) or an [Azure CLI command](../../../azure-resource-manager/management/resource-providers-and-types.md#azure-cli). If you are not the subscription owner, ask the *Subscription Owner* or someone with a role of *admin* to complete the registration for you or ask for the **/register/action** privileges to be granted to your account.
+
+## Get the keys for your resource
+
+Use the [Get-AzCognitiveServicesAccountKey](/powershell/module/az.cognitiveservices/get-azcognitiveservicesaccountkey) command to get the keys for your resource.
+
+```azurepowershell-interactive
+Get-AzCognitiveServicesAccountKey -Name multi-service-resource -ResourceGroupName ai-services-resource-group
+```
+
+[!INCLUDE [environment-variables](environment-variables.md)]
+
+## Pricing tiers and billing
+
+Pricing tiers (and the amount you get billed) are based on the number of transactions you send using your authentication information. Each pricing tier specifies the:
+* maximum number of allowed transactions per second (TPS).
+* service features enabled within the pricing tier.
+* The cost for a predefined number of transactions. Going above this amount will cause an extra charge as specified in the [pricing details](https://azure.microsoft.com/pricing/details/cognitive-services/custom-vision-service/) for your service.
+
+## Get current quota usage for your resource
+
+Use the [Get-AzCognitiveServicesAccountUsage](/powershell/module/az.cognitiveservices/get-azcognitiveservicesaccountusage) command to get the usage for your resource.
+
+```azurepowershell-interactive
+Get-AzCognitiveServicesAccountUsage -ResourceGroupName ai-services-resource-group -Name multi-service-resource
+```
+
+## Clean up resources
+
+If you want to clean up and remove an Azure AI services resource, you can delete it or the resource group. Deleting the resource group also deletes any other resources contained in the group.
+
+To remove the resource group and its associated resources, use the [Remove-AzResourceGroup](/powershell/module/az.resources/remove-azresourcegroup) command.
+
+```azurepowershell-interactive
+Remove-AzResourceGroup -Name ai-services-resource-group
+```
+
+If you need to recover a deleted resource, see [Recover deleted Azure AI services resources](../../manage-resources.md).

articles/ai-services/multi-service-resource.md

@@ -56,6 +56,12 @@ The multi-service resource enables access to the following Azure AI services wit
 
 ::: zone-end
 
+::: zone pivot="azpowershell"
+
+[!INCLUDE [Azure PowerShell quickstart](includes/quickstarts/management-azpowershell.md)]
+
+::: zone-end
+
 ::: zone pivot="programming-language-csharp"
 
 [!INCLUDE [C# SDK quickstart](includes/quickstarts/management-csharp.md)]

articles/ai-services/openai/chatgpt-quickstart.md

@@ -61,3 +61,9 @@ Use this article to get started using Azure OpenAI.
 [!INCLUDE [REST API quickstart](includes/chatgpt-rest.md)]
 
 ::: zone-end
+
+::: zone pivot="programming-language-powershell"
+
+[!INCLUDE [PowerShell quickstart](includes/chatgpt-powershell.md)]
+
+::: zone-end

articles/ai-services/openai/dall-e-quickstart.md

@@ -55,6 +55,12 @@ zone_pivot_groups: openai-quickstart-dall-e
 
 ::: zone-end
 
+::: zone pivot="programming-language-powershell"
+
+[!INCLUDE [PowerShell quickstart](includes/dall-e-powershell.md)]
+
+::: zone-end
+
 ::: zone pivot="rest-api"
 
 [!INCLUDE [REST API quickstart](includes/dall-e-rest.md)]

articles/ai-services/openai/how-to/create-resource.md

@@ -37,6 +37,12 @@ In this article, you review examples for creating and deploying resources in the
 
 ::: zone-end
 
+::: zone pivot="ps"
+
+[!INCLUDE [Azure PowerShell resource](../includes/create-resource-powershell.md)]
+
+::: zone-end
+
 ## Next steps
 
 - Make API calls and generate text with [Azure OpenAI Service quickstarts](../quickstart.md).