Merge pull request #186777 from MicrosoftDocs/master

Merge master to live, 4 AM

Author: v-ccolin

.openpublishing.redirection.healthcare-apis.json

@@ -374,7 +374,7 @@
     },
     {
         "source_path_from_root": "/articles/healthcare-apis/data-transformation/move-to-synapse.md",
-        "redirect_url": "/azure/healthcare-apis/fhir/move-to-synapse",
+        "redirect_url": "/azure/healthcare-apis/fhir/copy-to-synapse",
         "redirect_document_id": true
     },
     {
@@ -429,7 +429,7 @@
     },
     {
         "source_path_from_root": "/articles/healthcare-apis/azure-api-for-fhir/access-fhir-postman-tutorial.md",
-        "redirect_url": "/azure/healthcare-apis/use-postman",
+        "redirect_url": "/azure/healthcare-apis/fhir/use-postman",
         "redirect_document_id": true
     },
     {

.openpublishing.redirection.json

@@ -45246,6 +45246,16 @@
     "source_path_from_root": "/articles/azure/virtual-desktop/azure-advisor.md",
     "redirect_url": "/azure/advisor/advisor-overview",
     "redirect_document_id": false
-    }
+    },
+    {
+      "source_path_from_root": "/articles/azure/cognitive-services/translator/tutorial-wpf-translation-csharp.md",
+      "redirect_url": "/ai-builder/flow-text-translation?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json",
+      "redirect_document_id": false
+      },
+      {
+        "source_path_from_root": "/articles/azure/cognitive-services/translator/tutorial-build-flask-app-translation-synthesis.md",
+        "redirect_url": "/learn/modules/translate-text-with-translator-service?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json",
+        "redirect_document_id": false
+        }
   ]
 }

articles/aks/azure-files-volume.md

@@ -4,7 +4,7 @@ titleSuffix: Azure Kubernetes Service
 description: Learn how to manually create a volume with Azure Files for use with multiple concurrent pods in Azure Kubernetes Service (AKS)
 services: container-service
 ms.topic: article
-ms.date: 01/18/2022
+ms.date: 01/29/2022
 
 
 #Customer intent: As a developer, I want to learn how to manually create and attach storage using Azure Files to a pod in AKS.
@@ -19,7 +19,7 @@ For more information on Kubernetes volumes, see [Storage options for application
 
 ## Before you begin
 
-This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart [using the Azure CLI][aks-quickstart-cli] or [using the Azure portal][aks-quickstart-portal].
+This article assumes that you have an existing AKS 1.21 or above cluster. If you need an AKS cluster, see the AKS quickstart [using the Azure CLI][aks-quickstart-cli] or [using the Azure portal][aks-quickstart-portal].
 
 You also need the Azure CLI version 2.0.59 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
 
@@ -93,10 +93,12 @@ spec:
         mountPath: /mnt/azure
   volumes:
   - name: azure
-    azureFile:
-      secretName: azure-secret
-      shareName: aksshare
-      readOnly: false
+    csi:
+      driver: file.csi.azure.com
+      volumeAttributes:
+        secretName: azure-secret  # required
+        shareName: aksshare  # required
+        mountOptions: "dir_mode=0777,file_mode=0777,cache=strict,actimeo=30"  # optional
 ```
 
 Use the `kubectl` command to create the pod.
@@ -105,37 +107,11 @@ Use the `kubectl` command to create the pod.
 kubectl apply -f azure-files-pod.yaml
 ```
 
-You now have a running pod with an Azure Files share mounted at */mnt/azure*. You can use `kubectl describe pod mypod` to verify the share is mounted successfully. The following condensed example output shows the volume mounted in the container:
-
-```
-Containers:
-  mypod:
-    Container ID:   docker://86d244cfc7c4822401e88f55fd75217d213aa9c3c6a3df169e76e8e25ed28166
-    Image:          mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
-    Image ID:       docker-pullable://nginx@sha256:9ad0746d8f2ea6df3a17ba89eca40b48c47066dfab55a75e08e2b70fc80d929e
-    State:          Running
-      Started:      Sat, 02 Mar 2019 00:05:47 +0000
-    Ready:          True
-    Mounts:
-      /mnt/azure from azure (rw)
-      /var/run/secrets/kubernetes.io/serviceaccount from default-token-z5sd7 (ro)
-[...]
-Volumes:
-  azure:
-    Type:        AzureFile (an Azure File Service mount on the host and bind mount to the pod)
-    SecretName:  azure-secret
-    ShareName:   aksshare
-    ReadOnly:    false
-  default-token-z5sd7:
-    Type:        Secret (a volume populated by a Secret)
-    SecretName:  default-token-z5sd7
-[...]
-```
+You now have a running pod with an Azure Files share mounted at */mnt/azure*. You can use `kubectl describe pod mypod` to verify the share is mounted successfully. 
 
 ## Mount file share as a persistent volume
  - Mount options
-
-The default value for *fileMode* and *dirMode* is *0777* for Kubernetes version 1.15 and above. The following example sets *0755* on the *PersistentVolume* object:
+> The default value for *fileMode* and *dirMode* is *0777* for Kubernetes version 1.15 and above.
 
 ```yaml
 apiVersion: v1
@@ -147,43 +123,25 @@ spec:
     storage: 5Gi
   accessModes:
     - ReadWriteMany
-  azureFile:
-    secretName: azure-secret
-    secretNamespace: default
-    shareName: aksshare
-    readOnly: false
-  mountOptions:
-  - dir_mode=0755
-  - file_mode=0755
-  - uid=1000
-  - gid=1000
-  - mfsymlinks
-  - nobrl
-```
-
-To update your mount options, create a *azurefile-mount-options-pv.yaml* file with a *PersistentVolume*. For example:
-
-```yaml
-apiVersion: v1
-kind: PersistentVolume
-metadata:
-  name: azurefile
-spec:
-  capacity:
-    storage: 5Gi
-  accessModes:
-    - ReadWriteMany
-  azureFile:
-    secretName: azure-secret
-    shareName: aksshare
+  persistentVolumeReclaimPolicy: Retain
+  csi:
+    driver: file.csi.azure.com
     readOnly: false
+    volumeHandle: unique-volumeid  # make sure this volumeid is unique in the cluster
+    volumeAttributes:
+      resourceGroup: EXISTING_RESOURCE_GROUP_NAME  # optional, only set this when storage account is not in the same resource group as agent node
+      shareName: aksshare
+    nodeStageSecretRef:
+      name: azure-secret
+      namespace: default
   mountOptions:
-  - dir_mode=0777
-  - file_mode=0777
-  - uid=1000
-  - gid=1000
-  - mfsymlinks
-  - nobrl
+    - dir_mode=0777
+    - file_mode=0777
+    - uid=0
+    - gid=0
+    - mfsymlinks
+    - cache=strict
+    - nosharesock
 ```
 
 Create a *azurefile-mount-options-pvc.yaml* file with a *PersistentVolumeClaim* that uses the *PersistentVolume*. For example:
@@ -238,11 +196,11 @@ kubectl apply -f azure-files-pod.yaml
 
 ## Next steps
 
-For associated best practices, see [Best practices for storage and backups in AKS][operator-best-practices-storage].
+For Azure File CSI driver parameters, see [CSI driver parameters][CSI driver parameters].
 
-For more information about AKS clusters interact with Azure Files, see the [Kubernetes plugin for Azure Files][kubernetes-files].
+For information about AKS 1.20 or below clusters interact with Azure Files, see the [Kubernetes plugin for Azure Files][kubernetes-files].
 
-For storage class parameters, see [Static Provision(bring your own file share)](https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/master/docs/driver-parameters.md#static-provisionbring-your-own-file-share).
+For associated best practices, see [Best practices for storage and backups in AKS][operator-best-practices-storage].
 
 <!-- LINKS - external -->
 [kubectl-create]: https://kubernetes.io/docs/user-guide/kubectl/v1.8/#create
@@ -251,11 +209,12 @@ For storage class parameters, see [Static Provision(bring your own file share)](
 [kubernetes-volumes]: https://kubernetes.io/docs/concepts/storage/volumes/
 [smb-overview]: /windows/desktop/FileIO/microsoft-smb-protocol-and-cifs-protocol-overview
 [kubernetes-security-context]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
+[CSI driver parameters]: https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/master/docs/driver-parameters.md#static-provisionbring-your-own-file-share
 
 <!-- LINKS - internal -->
 [aks-quickstart-cli]: kubernetes-walkthrough.md
 [aks-quickstart-portal]: kubernetes-walkthrough-portal.md
 [install-azure-cli]: /cli/azure/install-azure-cli
 [operator-best-practices-storage]: operator-best-practices-storage.md
 [concepts-storage]: concepts-storage.md
-[persistent-volume-example]: #mount-file-share-as-a-persistent-volume
+[persistent-volume-example]: #mount-file-share-as-a-persistent-volume

articles/api-management/TOC.yml

@@ -126,6 +126,8 @@
               href: edit-api.md
             - name: Configure Service Fabric backend
               href: how-to-configure-service-fabric-backend.md
+            - name: Import SAP OData metadata
+              href: sap-api.md
       - name: Provision and scale
         items:
             - name: Capacity metric

articles/api-management/media/sap-api/get-metadata-operation.png

@@ -0,0 +1,135 @@
+---
+title: Import an SAP API using the Azure portal | Microsoft Docs
+titleSuffix: 
+description: Learn how to import OData metadata from SAP as an API to Azure API Management
+ms.service: api-management
+author: martinpankraz
+ms.author: mapankra
+ms.topic: how-to
+ms.date: 01/26/2022
+ms.custom: 
+---
+
+# Import SAP OData metadata as an API
+
+This article shows how to import an OData service using its metadata description. In this article, [SAP Gateway](https://help.sap.com/viewer/product/SAP_GATEWAY) serves as an example. However, you can apply the approach to any OData-compliant service.
+
+In this article, you'll: 
+> [!div class="checklist"]
+> * Convert OData metadata to an OpenAPI specification
+> * Import the OpenAPI specification to API Management
+> * Complete API configuration
+> * Test the API in the Azure portal
+
+## Prerequisites
+
+- An existing API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).
+- An SAP system and service exposed as OData v2 or v4. 
+- If your SAP backend uses a self-signed certificate (for test purposes), you may need to disable the verification of the trust chain for SSL. To do so, configure a [backend](backends.md) in your API Management instance:
+    1. In the Azure portal, under **APIs**, select **Backends** > **+ Add**.
+    1.  Add a **Custom URL** pointing to the SAP backend service.
+    1.  Uncheck **Validate certificate chain** and **Validate certificate name**. 
+
+    > [!NOTE]
+    > For production scenarios, use proper certificates for end-to-end SSL verification.
+
+## Convert OData metadata to OpenAPI JSON
+
+1. Retrieve metadata XML from your SAP service. Use one of these methods: 
+
+   * Use the SAP Gateway Client (transaction `/IWFND/GW_CLIENT`), or 
+   * Make a direct HTTP call to retrieve the XML:
+   `http://<OData server URL>:<port>/<path>/$metadata`.
+
+1. Convert the OData XML to OpenAPI JSON format. Use an OASIS open-source tool for [OData v2](https://github.com/oasis-tcs/odata-openapi/tree/main/tools) or [OData v4](https://github.com/oasis-tcs/odata-openapi/tree/main/lib), depending on your metadata XML. 
+
+   The following is an example command to convert OData v2 XML for the test service `epm_ref_apps_prod_man_srv`:
+
+   ```console
+   odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
+    --scheme https --host <your IP address>:<your SSL port> \
+    ./epm_ref_apps_prod_man_srv.xml
+   ```
+    > [!NOTE]
+    > * For test purposes with a single XML file, you can use a [web-based converter](https://aka.ms/ODataOpenAPI) based on the open-source tool.
+    > * With the tool or the web-based converter, specifying the \<IP address>:\<port> of your SAP OData server is optional. Alternatively, add this information later in your generated OpenAPI specification or after importing to API Management.
+
+1. Save the `openapi-spec.json` file locally for import to API Management.
+
+[!INCLUDE [api-management-navigate-to-instance](../../includes/api-management-navigate-to-instance.md)]
+
+## Import and publish backend API 
+
+1. From the side navigation menu, under the **APIs** section, select **APIs**.
+1. Under **Create a new definition**, select **OpenAPI specification**.
+
+    :::image type="content" source="./media/import-api-from-oas/oas-api.png" alt-text="OpenAPI specifiction":::
+
+1. Click **Select a file**, and select the `openapi-spec.json` file that you saved locally in a previous step.
+
+1. Enter API settings. You can set the values during creation or configure them later by going to the **Settings** tab. 
+    * In **API URL suffix**, we recommend using the same URL path as in the original SAP service.
+
+    * For more information about API settings, see [Import and publish your first API](import-and-publish.md#import-and-publish-a-backend-api) tutorial.
+
+1. Select **Create**.
+
+> [!NOTE]
+> The API import limitations are documented in [another article](api-management-api-import-restrictions.md).
+
+
+## Complete API configuration
+
+[Add](add-api-manually.md#add-and-test-an-operation) the following three operations to the API that you imported.
+
+- `GET /$metadata`
+
+    |Operation  |Description  |Further configuration for operation  |
+    |---------|---------|---------|
+    |`GET /$metadata`     |   Enables API Management to reach the `$metadata` endpoint, which is required for client integration with the OData server.<br/><br/>This required operation isn't included in the OpenAPI specification that you generated and imported.    |  Add a `200 OK` response.       |
+
+    :::image type="content" source="media/sap-api/get-metadata-operation.png" alt-text="Get metadata operation":::
+
+- `HEAD /` 
+
+    |Operation  |Description  |Further configuration for operation  |
+    |---------|---------|---------|
+    |`HEAD /`     | Enables the client to exchange Cross Site Request Forgery (CSRF) tokens with the SAP server, when required.<br/><br/>SAP also allows CSRF token exchange using the GET verb.<br/><br/> CSRF token exchange isn’t covered in this article. See an example API Management [policy snippet](https://github.com/Azure/api-management-policy-snippets/blob/master/examples/Get%20X-CSRF%20token%20from%20SAP%20gateway%20using%20send%20request.policy.xml)     to broker token exchange.     |     N/A    |
+
+    :::image type="content" source="media/sap-api/head-root-operation.png" alt-text="Operation to fetch tokens":::
+
+- `GET /`
+
+    Operation  |Description  |Further configuration for operation  |
+    |---------|---------|---------|
+    |`GET /`     |   Enables policy configuration at service root.   |    Configure the following inbound [rewrite-uri](api-management-transformation-policies.md#RewriteURL) policy to append a trailing slash to requests that are forwarded to service root:<br/><br>    `<rewrite-uri template="/" copy-unmatched-params="true" />` <br/><br/>This policy removes potential ambiguity of requests with or without trailing slashes, which are treated differently by some backends.|
+
+    :::image type="content" source="media/sap-api/get-root-operation.png" alt-text="Get operation for service root":::
+
+Also, configure authentication to your backend using an appropriate method for your environment. For examples, see [API Management authentication policies](api-management-authentication-policies.md).
+
+## Test your API
+
+1. Navigate to your API Management instance.
+1. From the side navigation menu, under the **APIs** section, select **APIs**.
+1. Under **All APIs**, select your imported API.
+1. Select the **Test** tab to access the test console. 
+1. Select an operation, enter any required values, and select **Send**. 
+
+    For example, test the `GET /$metadata` call to verify connectivity to the SAP backend
+1. View the response. To troubleshoot, [trace](api-management-howto-api-inspector.md) the call.
+1. When testing is complete, exit the test console.
+
+## Production considerations
+
+* See an [example end-to-end scenario](https://blogs.sap.com/2021/08/12/.net-speaks-odata-too-how-to-implement-azure-app-service-with-sap-odata-gateway/) to integrate API Management with an SAP gateway.
+* Control access to an SAP backend using API Management policies. See policy snippets for [SAP principal propagation](https://github.com/Azure/api-management-policy-snippets/blob/master/examples/Request%20OAuth2%20access%20token%20from%20SAP%20using%20AAD%20JWT%20token.xml) and [fetching an X-CSRF token](https://github.com/Azure/api-management-policy-snippets/blob/master/examples/Get%20X-CSRF%20token%20from%20SAP%20gateway%20using%20send%20request.policy.xml).
+* For guidance to deploy, manage, and migrate APIs at scale, see:
+    * [Automated API deployments with APIOps](/architecture/example-scenario/devops/automated-api-deployments-apiops)
+    * [CI/CD for API Management using Azure Resource Manager templates](devops-api-development-templates.md).
+
+[!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]
+
+## Next steps
+> [!div class="nextstepaction"]
+> [Transform and protect a published API](transform-api.md)

articles/api-management/media/sap-api/get-root-operation.png

@@ -75,7 +75,7 @@ The free certificate comes with the following limitations:
 - All the above must be met for successful certificate issuances and renewals
 
 # [Subdomain](#tab/subdomain)
-- Must have CNAME mapped _directly_ to <app-name>.azurewebsites.net; using services that proxy the CNAME value will block certificate issuance and renewal
+- Must have CNAME mapped _directly_ to \<app-name\>.azurewebsites.net; using services that proxy the CNAME value will block certificate issuance and renewal
 - All the above must be met for successful certificate issuance and renewals
 
 -----

articles/api-management/media/sap-api/head-root-operation.png

@@ -51,7 +51,7 @@ See how data, including name, birth date, machine-readable zone, and expiration
 > [!NOTE]
 > Form Recognizer studio is available with the preview (v3.0) API.
 
-1. On the Form Recognizer Studio home page, select **Invoices**
+1. On the Form Recognizer Studio home page, select **Identity documents**
 
 1. You can analyze the sample invoice or select the **+ Add** button to upload your own sample.