Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into yelevin/connect-aws-s3-waf

Author: yelevin

articles/ai-services/openai/how-to/use-your-data-securely.md

@@ -144,7 +144,7 @@ The [custom subdomain](/azure/ai-services/cognitive-services-custom-subdomains)
 
 ### Enable managed identity
 
-To allow your Azure AI Search and Storage Account to recognize your Azure OpenAI service via Microsoft Entra ID authentication, you need to assign a managed identity for your Azure OpenAI service. The easiest way is to toggle on system assigned managed identity on Azure portal.
+To allow your Azure AI Search and Storage Account to recognize your Azure OpenAI Service via Microsoft Entra ID authentication, you need to assign a managed identity for your Azure OpenAI Service. The easiest way is to toggle on system assigned managed identity on Azure portal.
 :::image type="content" source="../media/use-your-data/openai-managed-identity.png" alt-text="A screenshot showing the system assigned managed identity option in the Azure portal." lightbox="../media/use-your-data/openai-managed-identity.png":::
 
 To set the managed identities via the management API, see [the management API reference documentation](/rest/api/aiservices/accountmanagement/accounts/update#identity).
@@ -175,7 +175,7 @@ This step can be skipped only if you have a [shared private link](#create-shared
 
 You can disable public network access of your Azure OpenAI resource in the Azure portal. 
 
-To allow access to your Azure OpenAI service from your client machines, like using Azure OpenAI Studio, you need to create [private endpoint connections](/azure/ai-services/cognitive-services-virtual-networks?tabs=portal#use-private-endpoints) that connect to your Azure OpenAI resource.
+To allow access to your Azure OpenAI Service from your client machines, like using Azure OpenAI Studio, you need to create [private endpoint connections](/azure/ai-services/cognitive-services-virtual-networks?tabs=portal#use-private-endpoints) that connect to your Azure OpenAI resource.
 
 
 ## Configure Azure AI Search
@@ -290,7 +290,7 @@ To enable the developers to use these resources to build applications, the admin
 
 ## Configure gateway and client
 
-To access the Azure OpenAI service from your on-premises client machines, one of the approaches is to configure Azure VPN Gateway and Azure VPN Client.
+To access the Azure OpenAI Service from your on-premises client machines, one of the approaches is to configure Azure VPN Gateway and Azure VPN Client.
 
 Follow [this guideline](/azure/vpn-gateway/tutorial-create-gateway-portal#VNetGateway) to create virtual network gateway for your virtual network.
 

articles/ai-services/openai/includes/dall-e-go.md

@@ -61,6 +61,7 @@ import (
 	"os"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
 )
 
@@ -75,19 +76,15 @@ func main() {
 		return
 	}
 
-	keyCredential, err := azopenai.NewKeyCredential(azureOpenAIKey)
-
-	if err != nil {
-		// handle error
-	}
+	keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
 
 	client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
 
 	if err != nil {
 		// handle error
 	}
 
-	resp, err := client.CreateImage(context.TODO(), azopenai.ImageGenerationOptions{
+	resp, err := client.GetImageGenerations(context.TODO(), azopenai.ImageGenerationOptions{
 		Prompt:         to.Ptr("a painting of a cat in the style of Dali"),
 		ResponseFormat: to.Ptr(azopenai.ImageGenerationResponseFormatURL),
 	}, nil)

articles/ai-services/openai/includes/go.md

@@ -38,6 +38,7 @@ import (
 	"os"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
 )
 
@@ -52,11 +53,7 @@ func main() {
 		return
 	}
 
-	keyCredential, err := azopenai.NewKeyCredential(azureOpenAIKey)
-
-	if err != nil {
-		// TODO: handle error
-	}
+	keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
 
 	client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
 
@@ -65,10 +62,10 @@ func main() {
 	}
 
 	resp, err := client.GetCompletions(context.TODO(), azopenai.CompletionsOptions{
-		Prompt:       []string{"What is Azure OpenAI, in 20 words or less"},
-		MaxTokens:    to.Ptr(int32(2048)),
-		Temperature:  to.Ptr(float32(0.0)),
-		Deployment: modelDeploymentID,
+		Prompt:         []string{"What is Azure OpenAI, in 20 words or less"},
+		MaxTokens:      to.Ptr(int32(2048)),
+		Temperature:    to.Ptr(float32(0.0)),
+		DeploymentName: &modelDeploymentID,
 	}, nil)
 
 	if err != nil {

articles/ai-services/openai/includes/use-your-data-go.md

@@ -80,15 +80,15 @@ ms.date: 03/07/2024
    		},
    		MaxTokens: to.Ptr[int32](512),
    		AzureExtensionsOptions: []azopenai.AzureChatExtensionConfigurationClassification{
-   			&azopenai.AzureCognitiveSearchChatExtensionConfiguration{
+   			&azopenai.AzureSearchChatExtensionConfiguration{
    				// This allows Azure OpenAI to use an Azure AI Search index.
    				//
    				// > Because the model has access to, and can reference specific sources to support its responses, answers are not only based on its pretrained knowledge
    				// > but also on the latest information available in the designated data source. This grounding data also helps the model avoid generating responses
    				// > based on outdated or incorrect information.
    				//
    				// Quote from here: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/use-your-data
-   				Parameters: &azopenai.AzureCognitiveSearchChatExtensionParameters{
+   				Parameters: &azopenai.AzureSearchChatExtensionParameters{
    					Endpoint:  &searchEndpoint,
    					IndexName: &searchIndex,
    					Authentication: &azopenai.OnYourDataAPIKeyAuthenticationOptions{
@@ -105,12 +105,9 @@ ms.date: 03/07/2024
    		log.Fatalf("ERROR: %s", err)
    	}
    
-   	// Contains contextual information from your Azure chat completion extensions, configured above in `AzureExtensionsOptions`
-   	msgContext := resp.Choices[0].Message.Context
-   
    	fmt.Fprintf(os.Stderr, "Extensions Context Role: %s\nExtensions Context (length): %d\n",
-   		*msgContext.Messages[0].Role,
-   		len(*msgContext.Messages[0].Content))
+   		*resp.Choices[0].Message.Role,
+   		len(*resp.Choices[0].Message.Content))
    
    	fmt.Fprintf(os.Stderr, "ChatRole: %s\nChat content: %s\n",
    		*resp.Choices[0].Message.Role,

articles/api-center/TOC.yml

@@ -46,7 +46,9 @@
   items:
       - name: Use metadata for governance
         href: metadata.md
-      - name: Analyze APIs using linting rules
+      - name: API analysis - Microsoft managed
+        href: enable-managed-api-analysis-linting.md
+      - name: API analysis - self-managed
         href: enable-api-analysis-linting.md
       - name: Discover shadow APIs with Dev Proxy
         href: discover-shadow-apis-dev-proxy.md
@@ -56,7 +58,7 @@
   items:
       - name: Self-host Azure API Center portal
         href: enable-api-center-portal.md
-      - name: Check if app calls APIs using minimal permissions with Dev Proxy
+      - name: Check API calls use minimal permissions with Dev Proxy
         href: check-minimal-api-permissions-dev-proxy.md
 - name: API center management and operations
   items:

articles/api-center/enable-api-analysis-linting.md

@@ -10,15 +10,18 @@ ms.custom: devx-track-azurecli
 # Customer intent: As an API program manager, I want to lint the API definitions in my organization's API center and analyze whether my APIs comply with my organization's API style guide.
 ---
 
-# Enable linting and analysis for API governance in your API center
+# Enable API analysis in your API center - self-managed
 
-This article shows how to enable linting to analyze API definitions in your organization's [API center](overview.md) for conformance with your organizations's API style rules. Linting generates an analysis report that you can access in your API center. Use API linting and analysis to detect common errors and inconsistencies in your API definitions.
+This article explains how to enable API analysis in [Azure API Center](overview.md) by manually setting up a linting engine and triggers. API analysis offers linting capabilities to analyze API definitions in your organization's API center. Linting ensures your API definitions adhere to organizational style rules, generating both individual and summary reports. Use API analysis to identify and correct common errors and inconsistencies in your API definitions.
+
+> [!NOTE]
+> In preview, Azure API Center can also automatically set up a linting engine and any required dependencies and triggers. [Learn more](enable-managed-api-analysis-linting.md). 
 
 > [!VIDEO https://www.youtube.com/embed/m0XATQaVhxA]
 
 ## Scenario overview
 
-In this scenario, you analyze API definitions in your API center by using the [Spectral](https://github.com/stoplightio/spectral) open source linting engine. An Azure Functions app runs the linting engine in response to events in your API center. Spectral checks that the APIs defined in a JSON or YAML specification document conform to the rules in a customizable API style guide. A report of API compliance is generated that you can view in your API center.
+In this scenario, you analyze API definitions in your API center by using the [Spectral](https://github.com/stoplightio/spectral) open source linting engine. An Azure Functions app runs the linting engine in response to events in your API center. Spectral checks that the APIs defined in a JSON or YAML specification document conform to the rules in a customizable API style guide. An analysis report is generated that you can view in your API center.
 
 The following diagram shows the steps to enable linting and analysis in your API center. 
 
@@ -322,7 +325,7 @@ To view the analysis report for an API definition in your API center:
 
 The **API Analysis Report** opens, and it displays the API definition and errors, warnings, and information based on the configured API style guide. The following screenshot shows an example of an API analysis report.
 
-:::image type="content" source="media/enable-api-analysis-linting/api-analysis-report.png" alt-text="Screenshot of an API analysis report in the portal.":::
+:::image type="content" source="media/enable-api-analysis-linting/api-analysis-report.png" alt-text="Screenshot of an API analysis report in the portal." lightbox="media/enable-api-analysis-linting/api-analysis-report.png":::
 
 ### API analysis summary
 
@@ -331,12 +334,13 @@ To view a summary of analysis reports for all API definitions in your API center
 1. In the portal, navigate to your API center.
 1. In the left-hand menu, under **Governance**, select **API Analysis**. The summary appears.
 
-    :::image type="content" source="media/enable-api-analysis-linting/api-analysis-summary.png" alt-text="Screenshot of the API analysis summary in the portal.":::
+    :::image type="content" source="media/enable-api-analysis-linting/api-analysis-summary.png" alt-text="Screenshot of the API analysis summary in the portal." lightbox="media/enable-api-analysis-linting/api-analysis-summary.png":::
 
 ## Related content
 
 Learn more about Event Grid:
 
+* [Enable API analysis in your API center - Microsoft managed](enable-managed-api-analysis-linting.md)
 * [System topics in Azure Event Grid](../event-grid/system-topics.md)
 * [Event Grid push delivery - concepts](../event-grid/concepts.md)
 * [Event Grid schema for Azure API Center](../event-grid/event-schema-api-center.md)

articles/api-center/enable-managed-api-analysis-linting.md

@@ -0,0 +1,122 @@
+---
+title: Managed API linting and analysis - Azure API Center
+description: Enable managed linting of API definitions in your API center to analyze compliance of APIs with the organization's API style guide.
+ms.service: azure-api-center
+ms.topic: how-to
+ms.date: 08/23/2024
+ms.author: danlep
+author: dlepow
+ms.custom: 
+# Customer intent: As an API developer or API program manager, I want to analyze the API definitions in my organization's API center for compliance with my organization's API style guide.
+---
+
+# Enable API analysis in your API center - Microsoft managed
+
+This article explains how to enable API analysis in [Azure API Center](overview.md) without having to manage it yourself (preview). API analysis offers linting capabilities to analyze API definitions in your organization's API center. Linting ensures your API definitions adhere to organizational style rules, generating both individual and summary reports. Use API analysis to identify and correct common errors and inconsistencies in your API definitions.
+
+> [!NOTE]
+> With managed linting and analysis, API Center sets up a linting engine and any required dependencies and triggers. You can also enable linting and analysis [manually](enable-api-analysis-linting.md). 
+
+In this scenario:
+
+1. Add a linting ruleset (API style guide) in your API center using the Visual Studio Code extension for Azure API Center.
+1. Azure API Center automatically runs linting when you add or update an API definition. It's also triggered for all API definitions when you deploy a ruleset to your API center.
+1. Review API analysis reports in the Azure portal to see how your API definitions conform to the style guide.
+1. Optionally customize the ruleset for your organization's APIs. Test the custom ruleset locally before deploying it to your API center. 
+
+## Limitations
+
+* Currently, only OpenAPI specification documents in JSON or YAML format are analyzed.
+* By default, you enable analysis with the [`spectral:oas` ruleset](https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules). To learn more about the built-in rules, see the [Spectral GitHub repo](https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md). 
+* Currently, you configure a single ruleset, and it's applied to all OpenAPI definitions in your API center.
+
+## Prerequisites
+
+* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
+* [Visual Studio Code](https://code.visualstudio.com/) 
+
+* The following Visual Studio Code extensions:
+    * [Azure API Center extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=apidev.azure-api-center)
+
+        > [!IMPORTANT]
+        > Enable managed API analysis using the API Center extension's pre-release version. When installing the extension, choose the pre-release version. Switch between release and pre-release versions any time via the extension's **Manage** button in the Extensions view.
+    * [Spectral extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)
+    
+## Enable API analysis using Visual Studio Code
+
+To enable API analysis using the default linting ruleset:
+
+1. In Visual Studio Code, open a folder that you'll use to manage rulesets for Azure API Center.
+1. Select the Azure API Center icon from the Activity Bar.
+1. In the API Center pane, expand the API center resource in which to enable API analysis.
+1. Right-click **Rules** and select **Enable API Analysis**.
+
+    :::image type="content" source="media/enable-managed-api-analysis-linting/enable-analysis-visual-studio-code.png" alt-text="Screenshot of enabling API linting and analysis in Visual Studio Code.":::
+
+A message notifies you after API analysis is successfully enabled. A folder for your API center is created in `.api-center-rules`, at the root of your working folder. The folder for your API center contains:
+ 
+* A `ruleset.yml` file that defines the default API style guide used by the linting engine.
+* A `functions` folder with an example custom function that you can use to extend the ruleset. 
+
+With analysis enabled, the linting engine analyzes API definitions in your API center based on the default ruleset and generates API analysis reports.
+
+## View API analysis reports
+
+View an analysis summary and the analysis reports for your API definitions in the Azure portal. After API definitions are analyzed, the reports list errors, warnings, and information based on the configured API style guide. 
+
+To view an analysis summary in your API center:
+
+1. In the portal, navigate to your API center.
+1. In the left-hand menu, under **Governance**, select **API Analysis**. The summary appears.
+
+    :::image type="content" source="media/enable-api-analysis-linting/api-analysis-summary.png" alt-text="Screenshot of the API analysis summary in the portal." lightbox="media/enable-api-analysis-linting/api-analysis-summary.png":::
+
+1. Optionally select the API Analysis Report icon for an API definition. The definition's API analysis report appears, as shown in the following screenshot.
+
+    :::image type="content" source="media/enable-api-analysis-linting/api-analysis-report.png" alt-text="Screenshot of an API analysis report in the portal." lightbox="media/enable-api-analysis-linting/api-analysis-report.png":::
+
+    > [!TIP]
+    > You can also view the API analysis report by selecting **Analysis** from the API definition's menu bar.
+
+## Customize ruleset
+
+You can customize the default ruleset or replace it as your organization's API style guide. For example, you can [extend the ruleset](https://docs.stoplight.io/docs/spectral/83527ef2dd8c0-extending-rulesets) or add [custom functions](https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions).
+
+To customize or replace the ruleset:
+
+1. In Visual Studio Code, open the `.api-center-rules` folder at the root of your working folder.
+1. In the folder for the API center resource, open the `ruleset.yml` file.
+1. Modify or replace the content as needed. 
+1. Save your changes to `ruleset.yml`.
+
+### Test ruleset locally
+
+Before deploying the custom ruleset to your API center, validate it locally. The Azure API Center extension for Visual Studio Code provides integrated support for API specification linting with Spectral.
+
+1. In Visual Studio Code, use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. 
+1. Type **Azure API Center: Set active API Style Guide** and hit **Enter**.
+1. Choose **Select Local File** and specify the `ruleset.yml` file that you customized. Hit **Enter**. 
+
+    This step makes the custom ruleset the active API style guide for linting.
+
+Now, when you open an OpenAPI-based API definition file, a local linting operation is automatically triggered in Visual Studio Code. Results are displayed inline in the editor and in the **Problems** window (**View > Problems** or **Ctrl+Shift+M**).
+
+:::image type="content" source="media/enable-managed-api-analysis-linting/validate-local-linting.png" alt-text="Screenshot of linting an API definition in Visual Studio Code." lightbox="media/enable-managed-api-analysis-linting/validate-local-linting.png":::
+
+Review the linting results. Make any necessary adjustments to the ruleset and continue to test it locally until it performs the way you want.
+
+### Deploy ruleset to your API center
+
+To deploy the custom ruleset to your API center:
+
+1. In Visual Studio Code, select the Azure API Center icon from the Activity Bar.
+1. In the API Center pane, expand the API center resource in which you customized the ruleset.
+1. Right-click **Rules** and select **Deploy Rules to API Center**.
+
+A message notifies you after the rules are successfully deployed to your API center. The linting engine uses the updated ruleset to analyze API definitions.
+
+To see the results of linting with the updated ruleset, view the API analysis reports in the portal. 
+
+## Related content
+
+* [Enable API analysis in your API center - self-managed](enable-api-analysis-linting.md)