Merge pull request #269581 from dlepow/43

[APIM] Policy updates for release

Author: prmerger-automator[bot]

articles/api-management/http-data-source-policy.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 03/07/2023
+ms.date: 03/19/2024
 ms.author: danlep
 ---
 
@@ -95,6 +95,7 @@ The `http-data-source` resolver policy configures the HTTP request and optionall
 
 * To configure and manage a resolver with this policy, see [Configure a GraphQL resolver](configure-graphql-resolver.md).
 * This policy is invoked only when resolving a single field in a matching GraphQL operation type in the schema. 
+* This policy supports GraphQL [union types](https://spec.graphql.org/October2021/#sec-Unions).
 
 ## Examples
 
@@ -167,7 +168,7 @@ type User {
 
 ### Resolver for GraphQL mutation
 
-The following example resolves a mutation that inserts data by making a `POST` request to an HTTP data source. The policy expression in the `set-body` policy of the HTTP request modifies a `name` argument that is passed in the GraphQL query as its body.  The body that is sent will look like the following JSON:
+The following example resolves a mutation that inserts data by making a `POST` request to an HTTP data source. The policy expression in the `set-body` policy of the HTTP request modifies a `name` argument that is passed in the GraphQL query as its body. The body that is sent will look like the following JSON:
 
 ``` json
 {
@@ -198,7 +199,7 @@ type User {
 <http-data-source>
     <http-request>
         <set-method>POST</set-method>
-        <set-url> https://data.contoso.com/user/create </set-url>
+        <set-url>https://data.contoso.com/user/create </set-url>
         <set-header name="Content-Type" exists-action="override">
             <value>application/json</value>
         </set-header>
@@ -212,6 +213,63 @@ type User {
 </http-data-source>
 ```
 
+### Resolver for GraphQL union type
+
+The following example resolves the `orderById` query by making an HTTP `GET` call to a backend data source and returns a JSON object that includes the customer ID and type. The customer type is a union of `RegisteredCustomer` and `GuestCustomer` types.
+
+#### Example schema
+
+```graphql
+type Query {
+  orderById(orderId: Int): Order
+}
+
+type Order {
+  customerId: Int!
+  orderId: Int!  
+  customer: Customer
+}
+
+enum AccountType {
+  Registered
+  Guest
+}
+
+union Customer = RegisteredCustomer | GuestCustomer
+
+type RegisteredCustomer {
+  accountType: AccountType!
+  customerId: Int!
+  customerGuid: String!
+  firstName: String!
+  lastName: String!
+  isActive: Boolean!
+}
+
+type GuestCustomer {
+  accountType: AccountType!
+  firstName: String!
+  lastName: String!
+}
+```
+
+#### Example policy
+
+For this example, we mock the customer results from an external source, and hard code the fetched results in the `set-body` policy. The `__typename` field is used to determine the type of the customer.
+
+```xml
+<http-data-source>
+    <http-request>
+        <set-method>GET</set-method>
+        <set-url>https://data.contoso.com/orders/</set-url>
+    </http-request>
+    <http-response>
+        <set-body>{"customerId": 12345, "accountType": "Registered", "__typename": "RegisteredCustomer" }
+        </set-body>
+    </http-response>
+</http-data-source>
+```
+
 ## Related policies
 
 * [GraphQL resolver policies](api-management-policies.md#graphql-resolver-policies)

articles/api-management/validate-azure-ad-token-policy.md

@@ -69,9 +69,9 @@ The `validate-azure-ad-token` policy enforces the existence and validity of a JS
 
 | Element             | Description                                                                                                                                                                                                                                                                                                                                           | Required |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| audiences           | Contains a list of acceptable audience claims that can be present on the token. If multiple audience values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. At least one audience must be specified. Policy expressions are allowed.                                                                    | No       |
+| audiences           | Contains a list of acceptable audience claims that can be present on the token. If multiple `audience` values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. Policy expressions are allowed.                                                                    | No       |
 | backend-application-ids | Contains a list of acceptable backend application IDs.  This is only required in advanced cases for the configuration of options and can generally be removed. Policy expressions aren't allowed. | No |
-| client-application-ids | Contains a list of acceptable client application IDs.  If multiple application-id elements are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds.  At least one application-id must be specified. Policy expressions aren't allowed. | Yes |
+| client-application-ids | Contains a list of acceptable client application IDs. If multiple `application-id` elements are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. If a client application ID isn't provided, one or more `audience` claims should be specified. Policy expressions aren't allowed. | No |
 | required-claims     | Contains a list of `claim` elements for claim values expected to be present on the token for it to be considered valid. When the `match` attribute is set to `all`, every claim value in the policy must be present in the token for validation to succeed. When the `match` attribute is set to `any`, at least one claim must be present in the token for validation to succeed. Policy expressions are allowed. | No       |
 
 ### claim attributes