Merge pull request #229841 from dlepow/wksprev

[APIM] Workspaces review updates

Author: JamesJBarnett

articles/api-management/api-management-howto-policies.md

@@ -7,7 +7,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 03/23/2022
+ms.date: 03/07/2023
 ms.author: danlep
 
 ---
@@ -83,7 +83,8 @@ Policy expressions provide a sophisticated means to control traffic and modify A
 API Management allows you to define policies at the following *scopes*, from most broad to most narrow:
 
 * Global (all APIs)
-* Product (APIs associated with a selected product)
+* Workspace (all APIs associated with a selected workspace)
+* Product (all APIs associated with a selected product)
 * API (all operations in an API)
 * Operation (single operation in an API) 
 

articles/api-management/api-management-policy-expressions.md

@@ -7,7 +7,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 01/13/2023
+ms.date: 03/07/2023
 ms.author: danlep
 ---
 # API Management policy expressions
@@ -200,12 +200,12 @@ The `context` variable is implicitly available in every policy [expression](api-
 |Context Variable|Allowed methods, properties, and parameter values|
 |----------------------|-------------------------------------------------------|
 |`context`|[`Api`](#ref-context-api): [`IApi`](#ref-iapi)<br /><br /> [`Deployment`](#ref-context-deployment)<br /><br /> Elapsed: `TimeSpan` - time interval between the value of `Timestamp` and current time<br /><br /> [`LastError`](#ref-context-lasterror)<br /><br /> [`Operation`](#ref-context-operation)<br /><br /> [`Product`](#ref-context-product)<br /><br /> [`Request`](#ref-context-request)<br /><br /> `RequestId`: `Guid` - unique request identifier<br /><br /> [`Response`](#ref-context-response)<br /><br /> [`Subscription`](#ref-context-subscription)<br /><br /> `Timestamp`: `DateTime` - point in time when request was received<br /><br /> `Tracing`: `bool` - indicates if tracing is on or off <br /><br /> [User](#ref-context-user)<br /><br /> [`Variables`](#ref-context-variables): `IReadOnlyDictionary<string, object>`<br /><br /> `void Trace(message: string)`|
-|<a id="ref-context-api"></a>`context.Api`|`Id`: `string`<br /><br /> `IsCurrentRevision`: `bool`<br /><br />  `Name`: `string`<br /><br /> `Path`: `string`<br /><br /> `Revision`: `string`<br /><br /> `ServiceUrl`: [`IUrl`](#ref-iurl)<br /><br /> `Version`: `string` |
+|<a id="ref-context-api"></a>`context.Api`|`Id`: `string`<br /><br /> `IsCurrentRevision`: `bool`<br /><br />  `Name`: `string`<br /><br /> `Path`: `string`<br /><br /> `Revision`: `string`<br /><br /> `ServiceUrl`: [`IUrl`](#ref-iurl)<br /><br /> `Version`: `string` <br /><br /> `Workspace`: [`IWorkspace`](#ref-iworkspace) |
 |<a id="ref-context-deployment"></a>`context.Deployment`|[`Gateway`](#ref-context-gateway)<br /><br /> `GatewayId`: `string` (returns 'managed' for managed gateways)<br /><br /> `Region`: `string`<br /><br /> `ServiceId`: `string`<br /><br /> `ServiceName`: `string`<br /><br /> `Certificates`: `IReadOnlyDictionary<string, X509Certificate2>`|
 |<a id="ref-context-gateway"></a>`context.Deployment.Gateway`|`Id`: `string` (returns 'managed' for managed gateways)<br /><br /> `InstanceId`: `string` (returns 'managed' for managed gateways)<br /><br /> `IsManaged`: `bool`|
 |<a id="ref-context-lasterror"></a>`context.LastError`|`Source`: `string`<br /><br /> `Reason`: `string`<br /><br /> `Message`: `string`<br /><br /> `Scope`: `string`<br /><br /> `Section`: `string`<br /><br /> `Path`: `string`<br /><br /> `PolicyId`: `string`<br /><br /> For more information about `context.LastError`, see [Error handling](api-management-error-handling-policies.md).|
 |<a id="ref-context-operation"></a>`context.Operation`|`Id`: `string`<br /><br /> `Method`: `string`<br /><br /> `Name`: `string`<br /><br /> `UrlTemplate`: `string`|
-|<a id="ref-context-product"></a>`context.Product`|`Apis`: `IEnumerable<`[`IApi`](#ref-iapi)`>`<br /><br /> `ApprovalRequired`: `bool`<br /><br /> `Groups`: `IEnumerable<`[`IGroup`](#ref-igroup)`>`<br /><br /> `Id`: `string`<br /><br /> `Name`: `string`<br /><br /> `State`: `enum ProductState {NotPublished, Published}`<br /><br /> `SubscriptionLimit`: `int?`<br /><br /> `SubscriptionRequired`: `bool`|
+|<a id="ref-context-product"></a>`context.Product`|`Apis`: `IEnumerable<`[`IApi`](#ref-iapi)`>`<br /><br /> `ApprovalRequired`: `bool`<br /><br /> `Groups`: `IEnumerable<`[`IGroup`](#ref-igroup)`>`<br /><br /> `Id`: `string`<br /><br /> `Name`: `string`<br /><br /> `State`: `enum ProductState {NotPublished, Published}`<br /><br /> `SubscriptionLimit`: `int?`<br /><br /> `SubscriptionRequired`: `bool`<br /><br /> `Workspace`: [`IWorkspace`](#ref-iworkspace)|
 |<a id="ref-context-request"></a>`context.Request`|`Body`: [`IMessageBody`](#ref-imessagebody) or `null` if request doesn't have a body.<br /><br /> `Certificate`: `System.Security.Cryptography.X509Certificates.X509Certificate2`<br /><br /> [`Headers`](#ref-context-request-headers): `IReadOnlyDictionary<string, string[]>`<br /><br /> `IpAddress`: `string`<br /><br /> `MatchedParameters`: `IReadOnlyDictionary<string, string>`<br /><br /> `Method`: `string`<br /><br /> `OriginalUrl`: [`IUrl`](#ref-iurl)<br /><br /> `Url`: [`IUrl`](#ref-iurl)<br /><br /> `PrivateEndpointConnection`: [`IPrivateEndpointConnection`](#ref-iprivateendpointconnection) or `null` if request doesn't come from a private endpoint connection.|
 |<a id="ref-context-request-headers"></a>`string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string)`|`headerName`: `string`<br /><br /> `defaultValue`: `string`<br /><br /> Returns comma-separated request header values or `defaultValue` if the header isn't found.|
 |<a id="ref-context-response"></a>`context.Response`|`Body`: [`IMessageBody`](#ref-imessagebody)<br /><br /> [`Headers`](#ref-context-response-headers): `IReadOnlyDictionary<string, string[]>`<br /><br /> `StatusCode`: `int`<br /><br /> `StatusReason`: `string`|
@@ -217,9 +217,10 @@ The `context` variable is implicitly available in every policy [expression](api-
 |<a id="ref-imessagebody"></a>`IMessageBody`|`As<T>(bool preserveContent = false): Where T: string, byte[], JObject, JToken, JArray, XNode, XElement, XDocument` <br /><br /> - The `context.Request.Body.As<T>` and `context.Response.Body.As<T>` methods read a request or response message body in specified type `T`. <br/><br/> - Or - <br/><br/>`AsFormUrlEncodedContent(bool preserveContent = false)` <br/></br>- The `context.Request.Body.AsFormUrlEncodedContent()` and `context.Response.Body.AsFormUrlEncodedContent()` methods read URL-encoded form data in a request or response message body and return an `IDictionary<string, IList<string>` object. The decoded object supports `IDictionary` operations and the following expressions: `ToQueryString()`, `JsonConvert.SerializeObject()`, `ToFormUrlEncodedContent().` <br/><br/> By default, the `As<T>` and `AsFormUrlEncodedContent()` methods:<br /><ul><li>Use the original message body stream.</li><li>Render it unavailable after it returns.</li></ul> <br />To avoid that and have the method operate on a copy of the body stream, set the `preserveContent` parameter to `true`, as shown in examples for the [set-body](set-body-policy.md#examples) policy.|
 |<a id="ref-iprivateendpointconnection"></a>`IPrivateEndpointConnection`|`Name`: `string`<br /><br /> `GroupId`: `string`<br /><br /> `MemberName`: `string`<br /><br />For more information, see the [REST API](/rest/api/apimanagement/current-ga/private-endpoint-connection/list-private-link-resources).|
 |<a id="ref-iurl"></a>`IUrl`|`Host`: `string`<br /><br /> `Path`: `string`<br /><br /> `Port`: `int`<br /><br /> [`Query`](#ref-iurl-query): `IReadOnlyDictionary<string, string[]>`<br /><br /> `QueryString`: `string`<br /><br /> `Scheme`: `string`|
-|<a id="ref-iuseridentity"></a>`IUserIdentity`|`Id`: `string`<br /><br /> `Provider`: `string`|
 |<a id="ref-isubscriptionkeyparameternames"></a>`ISubscriptionKeyParameterNames`|`Header`: `string`<br /><br /> `Query`: `string`|
 |<a id="ref-iurl-query"></a>`string IUrl.Query.GetValueOrDefault(queryParameterName: string, defaultValue: string)`|`queryParameterName`: `string`<br /><br /> `defaultValue`: `string`<br /><br /> Returns comma-separated query parameter values or `defaultValue` if the parameter isn't found.|
+|<a id="ref-iuseridentity"></a>`IUserIdentity`|`Id`: `string`<br /><br /> `Provider`: `string`|
+|<a id="ref-iworkspace"></a>`IWorkspace`|`Id`: `string`<br /><br /> `Name`: `string`|
 |<a id="ref-context-variables"></a>`T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T)`|`variableName`: `string`<br /><br /> `defaultValue`: `T`<br /><br /> Returns variable value cast to type `T` or `defaultValue` if the variable isn't found.<br /><br /> This method throws an exception if the specified type doesn't match the actual type of the returned variable.|
 |`BasicAuthCredentials AsBasic(input: this string)`|`input`: `string`<br /><br /> If the input parameter contains a valid HTTP Basic Authentication authorization request header value, the method returns an object of type `BasicAuthCredentials`; otherwise the method returns null.|
 |`bool TryParseBasic(input: this string, result: out BasicAuthCredentials)`|`input`: `string`<br /><br /> `result`: `out BasicAuthCredentials`<br /><br /> If the input parameter contains a valid HTTP Basic Authentication authorization value in the request header, the method returns `true` and the result parameter contains a value of type `BasicAuthCredentials`; otherwise the method returns `false`.|

articles/api-management/how-to-create-workspace.md

@@ -5,7 +5,7 @@ author: dlepow
 ms.topic: how-to
 ms.service: api-management
 ms.author: danlep
-ms.date: 02/22/2023
+ms.date: 03/07/2023
 ms.custom:
 ---
 
@@ -36,7 +36,7 @@ The new workspace appears in the list on the **Workspaces** page. Select the wor
 
 ## Assign users to workspace - portal
 
-After creating a workspace, assign permissions to users to manage the workspace's resources. Each workspace user must be assigned an RBAC role at the service level and at the workspace level.
+After creating a workspace, assign permissions to users to manage the workspace's resources. Each workspace user must be assigned a workspace-specific RBAC role at the service level and at the workspace level, or granted equivalent permissions using custom roles.
 
 At minimum, assign an *administrator* of the workspace. Optionally, assign permissions to other workspace collaborators.
 
@@ -53,8 +53,9 @@ At minimum, assign an *administrator* of the workspace. Optionally, assign permi
 1. Assign the administrator the following role:
     * **API Management Service Workspace API Product Manager**
 
-1. Assign the following role to other members of the workspace:
+1. Assign one of the following roles to other members of the workspace:
     * **API Management Service Workspace Member**
+    * **API Management Service Workspace API Product Manager**
 
 ### Assign a workspace-level role
 
@@ -65,7 +66,12 @@ At minimum, assign an *administrator* of the workspace. Optionally, assign permi
 
     * **API Management Workspace Owner** 
 
-1. Optionally, assign workspace-level roles to other workspace members to manage workspace APIs and other resources. The administrator of the workspace can also assign workspace-level roles.
+1. Optionally, assign one of the following workspace-level roles to other workspace members to manage workspace APIs and other resources. The administrator of the workspace can also assign workspace-level roles.
+
+    * **API Management Workspace Reader**
+    * **API Management Workspace Contributor**
+    * **API Management Workspace API Developer**
+    * **API Management Workspace API Product Manager**
 
 ## Next steps
 

articles/api-management/media/api-management-howto-policies/policy-scopes.png

@@ -1,13 +1,13 @@
 ---
 title: Workspaces in Azure API Management | Microsoft Docs
-description: Learn about workspaces in Azure API Management. Workspaces allow decentralized API development teams to manage and productize their own APIs, while a central API platform team maintains the API Management infrastructure. 
+description: Learn about workspaces (preview) in Azure API Management. Workspaces allow decentralized API development teams to manage and productize their own APIs, while a central API platform team maintains the API Management infrastructure. 
 services: api-management
 documentationcenter: ''
 author: dlepow
 
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 02/22/2023
+ms.date: 03/07/2023
 ms.author: danlep
 ms.custom: 
 ---
@@ -20,6 +20,8 @@ In API Management, *workspaces* allow decentralized API development teams to man
 
 > [!NOTE]
 > * Workspaces are a preview feature of API Management and subject to certain [limitations](#preview-limitations).
+> * This feature is being released during March and April 2023.
+> * Workspaces are supported in API Management REST API version 2022-09-01-preview or later.
 > * For pricing considerations, see [API Management pricing](https://azure.microsoft.com/pricing/details/api-management/).
 
 
@@ -81,9 +83,9 @@ The following resources can be managed in the workspaces preview.
 
 Azure RBAC is used to configure workspace collaborators' permissions to read and edit entities in the workspace. For a list of roles, see [How to use role-based access control in API Management](api-management-role-based-access-control.md).
 
-Workspace members must be assigned both a service-level role and a workspace-level role. The service-level role enables referencing service-level resources from workspace-level resources. For example, publish an API from a workspace with a service-level product, assign a service-level tag to an API, or organize a user into a workspace-level group to control API and product visibility.  
+Workspace members must be assigned both a service-level role and a workspace-level role, or granted equivalent permissions using custom roles. The service-level role enables referencing service-level resources from workspace-level resources. For example, publish an API from a workspace with a service-level product, assign a service-level tag to an API, or organize a user into a workspace-level group to control API and product visibility.  
 
-## Workspace constraints
+## Workspaces and other API Management features
 
 * **Infrastructure features** - API Management platform infrastructure features are managed on the service level only, not at the workspace level. These features include:
 
@@ -112,10 +114,14 @@ The following resources aren't currently supported in workspaces:
 
 * Client certificates 
 
+* Current DevOps tooling for API Management
+
 * Diagnostics 
 
 * Loggers 
 
+* Synthetic GraphQL APIs
+
 * User-assigned managed identity 
 
 Therefore, the following sample scenarios aren't currently supported in workspaces: 
@@ -132,6 +138,4 @@ Therefore, the following sample scenarios aren't currently supported in workspac
 
 ## Next steps
 
-* [Create a workspace](how-to-create-workspace.md)
-
-* Migrate API Management resources to a workspace
+* [Create a workspace](how-to-create-workspace.md)