зеркало из https://github.com/Azure/autorest.git
[Permissions] x-ms-permissions extension docs (#4439)
This commit is contained in:
Robert Lyon
GitHub
Родитель
a5b47c3c21
Коммит
6bafe1cc29
|
|
@ -40,8 +40,8 @@ The following documents describes AutoRest specific vendor extensions for [OpenA
|
|||
Those extensions are defined as additional description of the RestAPI, and do not trigger at the moment any changes in code generation.
|
||||
|
||||
- [x-ms-secret](#x-ms-secret) - This extension is used to annotate the secret property.
|
||||
|
||||
- [x-ms-identifiers](#x-ms-identifiers) - (InProgress) indicates the identifying properties of objects in the array
|
||||
- [x-ms-azure-rbac-permissions-required](#x-ms-azure-rbac-permissions-required) - (InProgress) Specify permission exceptions for autogenerated public [Azure REST API reference](https://docs.microsoft.com/rest/api/azure/) documentation.
|
||||
|
||||
# Generic Extensions
|
||||
|
||||
|
|
@ -1542,3 +1542,95 @@ This extension is used to annotate the secret property. The value type is boolea
|
|||
"x-ms-identifiers": ["propertyName"]
|
||||
}
|
||||
```
|
||||
|
||||
## x-ms-azure-rbac-permissions-required
|
||||
|
||||
(InProgress) Specify permission exceptions for autogenerated public [Azure REST API reference](https://docs.microsoft.com/rest/api/azure/) documentation.
|
||||
|
||||
The doc processor has an opt-in option to autogenerate the required permissions by parsing the API. However, there will be situations where the autogeneration of the required permissions is not accurate. This extension enables you to specify permission exceptions for individual APIs.
|
||||
|
||||
**Permissions example #1**
|
||||
|
||||
Here is a [Virtual Machines - Get](https://docs.microsoft.com/rest/api/compute/virtual-machines/get) permissions example that **does not** require the `x-ms-azure-rbac-permissions-required` extension:
|
||||
|
||||
```
|
||||
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}?api-version=2021-11-01
|
||||
```
|
||||
|
||||
Autogenerated permissions from doc processor:
|
||||
|
||||
`Microsoft.Compute/virtualMachines/read`
|
||||
|
||||
**Permissions example #2**
|
||||
|
||||
Here is an [Assignments - Create Or Update](https://docs.microsoft.com/rest/api/blueprints/assignments/create-or-update) permissions example that **does** require the `x-ms-azure-rbac-permissions-required` extension:
|
||||
|
||||
```
|
||||
PUT https://management.azure.com/{resourceScope}/providers/Microsoft.Blueprint/blueprintAssignments/{assignmentName}?api-version=2018-11-01-preview
|
||||
```
|
||||
|
||||
Autogenerated permissions from doc processor:
|
||||
|
||||
`Microsoft.Blueprint/blueprintAssignments/write`
|
||||
|
||||
Actual permissions required to call API:
|
||||
|
||||
`Microsoft.Blueprint/blueprintAssignments/write and Microsoft.ManagedIdentity/userAssignedIdentities/assign/action`
|
||||
|
||||
**Schema**:
|
||||
|
||||
| Field Name | Type | Description |
|
||||
| --------------------------- | :--------: | ------------------------------------------------------------------------------------ |
|
||||
| `actions` | `string` | List of the required action permissions for this API. |
|
||||
| `dataActions` | `string` | List of the required data action permissions for this API. |
|
||||
| `rolesWithThesePermissions` | `[string]` | An array of roles that have the required permissions for this API. |
|
||||
| `moreInfoLink` | `string` | Link formatted as markdown with more information about the permissions for this API. |
|
||||
|
||||
For a list roles, see [Azure built-in roles](https://docs.microsoft.com/azure/role-based-access-control/built-in-roles).
|
||||
|
||||
```json5
|
||||
"xmsPermissions": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"actions": {
|
||||
"type": "string"
|
||||
},
|
||||
"dataActions": {
|
||||
"type": "string"
|
||||
},
|
||||
"rolesWithThesePermissions": [
|
||||
"type": "string"
|
||||
],
|
||||
"moreInfoLink": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
|
||||
```json5
|
||||
"x-ms-azure-rbac-permissions-required": {
|
||||
"actions": "Microsoft.Blueprint/blueprintAssignments/write and Microsoft.ManagedIdentity/userAssignedIdentities/assign/action",
|
||||
"dataActions": "",
|
||||
"rolesWithThesePermissions": [
|
||||
"Blueprint Operator"
|
||||
],
|
||||
"moreInfoLink": "[Learn more](https://docs.microsoft.com/azure/governance/blueprints/how-to/configure-for-blueprint-operator)"
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
|
||||
```json5
|
||||
"x-ms-azure-rbac-permissions-required": {
|
||||
"actions": "",
|
||||
"dataActions": "Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action or (Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete and Microsoft.Storage/storageAccounts/queueServices/queues/messages/read)",
|
||||
"rolesWithThesePermissions": [
|
||||
"Storage Queue Data Message Processor",
|
||||
"Storage Queue Data Contributor"
|
||||
],
|
||||
"moreInfoLink": "[Authorize access to blobs and queues using Azure Active Directory](https://docs.microsoft.com/azure/storage/blobs/authorize-access-azure-active-directory)"
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -2,11 +2,12 @@
|
|||
|
||||
# Archboard DPG/RLC feedback loop
|
||||
|
||||
If you went to SDK archboard as a service team, you may have encounter feedback on modification that you have to apply to your Swagger going forward
|
||||
If you went to SDK archboard as a service team, you may have encounter feedback on modification that you have to apply to your Swagger going forward
|
||||
to generate your SDK using [DPG/RLC](https://aka.ms/azsdk/dpcodegen). This document tries to clarify some common patterns and well known modifications you need to
|
||||
apply to your Swagger and/or Readme.
|
||||
|
||||
Content:
|
||||
|
||||
- [Need for more/less SDK package(s)](#need-for-moreless-sdk-packages)
|
||||
- [Rename an operation](#rename-an-operation)
|
||||
- [Rename an operation group (or rename a sub-client)](#rename-an-operation-group-or-rename-a-sub-client)
|
||||
|
|
@ -21,7 +22,7 @@ Content:
|
|||
## Need for more/less SDK package(s)
|
||||
|
||||
If you got as a feedback that your API needs to split across several packages, or two packages should be merged into one, then
|
||||
structure your Swaggers to have exactly one folder per package. Most of the work is re-organizing files and Readme. Example of hierarchy on
|
||||
structure your Swaggers to have exactly one folder per package. Most of the work is re-organizing files and Readme. Example of hierarchy on
|
||||
the [RestAPI spec repo](https://github.com/Azure/azure-rest-api-specs):
|
||||
|
||||
```
|
||||
|
|
@ -42,13 +43,15 @@ Operation name are directly OperationID in Swagger. Just rename the OperationID
|
|||
|
||||
Note: If your operation contains an `_`, just change the second part as the first is an operation group.
|
||||
|
||||
``` json
|
||||
```json
|
||||
"operationId": "SomethingToDoOperation",
|
||||
...
|
||||
"operationId": "MyGroup_SomethingElseToDoOperation",
|
||||
```
|
||||
|
||||
becomes
|
||||
``` json
|
||||
|
||||
```json
|
||||
"operationId": "BuildTheThing",
|
||||
...
|
||||
"operationId": "MyGroup_BuildSomethingElse",
|
||||
|
|
@ -59,11 +62,13 @@ becomes
|
|||
Operation groups are the first part of an OperationID in Swagger, before the `_` character. To rename an operation group, you need to rename all OperationID that
|
||||
starts with the operation group prefix (there is likely many of them).
|
||||
|
||||
``` json
|
||||
```json
|
||||
"operationId": "MyGroup_BuildSomethingElse",
|
||||
```
|
||||
|
||||
becomes
|
||||
``` json
|
||||
|
||||
```json
|
||||
"operationId": "NewGroup_BuildSomethingElse",
|
||||
```
|
||||
|
||||
|
|
@ -71,27 +76,31 @@ becomes
|
|||
|
||||
Don't use operation groups in your OperationID (remove them if they exist). For any operation with an `_` character, remove the first part.
|
||||
|
||||
``` json
|
||||
```json
|
||||
"operationId": "MyGroup_BuildSomethingElse",
|
||||
```
|
||||
|
||||
becomes
|
||||
``` json
|
||||
|
||||
```json
|
||||
"operationId": "BuildSomethingElse",
|
||||
```
|
||||
|
||||
## Need one client/builder with sub-clients
|
||||
|
||||
- Use operation groups, and name them as you want your subclients to be called. Operation group can be create in Swagger by using the `_` character in the OperationID
|
||||
(`OperationGroupName_OperationName`)
|
||||
- For C#, use `single-top-level-client: true`
|
||||
- Use operation groups, and name them as you want your subclients to be called. Operation group can be create in Swagger by using the `_` character in the OperationID
|
||||
(`OperationGroupName_OperationName`)
|
||||
- For C#, use `single-top-level-client: true`
|
||||
|
||||
For instance, this:
|
||||
``` json
|
||||
|
||||
```json
|
||||
"operationId": "MyGroup_BuildSomethingElse",
|
||||
```
|
||||
|
||||
Will create a subclient for MyGroup, that will have an operation called BuildSomethingElse.
|
||||
In various languages this could looks like (pseudo-code):
|
||||
|
||||
```
|
||||
MyServiceClient(endpoint, credentials).MyGroup().BuildSomethingElse() // C#
|
||||
|
||||
|
|
@ -100,17 +109,17 @@ MyServiceClient(endpoint, credentials).my_group.build_something_else() # Python
|
|||
|
||||
## Need two or more service clients (regardless of if some needs subclients or not)
|
||||
|
||||
- Make sure you don't have one Swagger with operations that are designed to be in two different clients.
|
||||
- Make sure you don't have one Swagger with operations that are designed to be in two different clients.
|
||||
Split Swagger files in multiple swagger files if necessary: clients should correspond to a clear set of Swagger files.
|
||||
- Define tags in `Readme.md` for each client input files. Use the `batch` autorest option to create the two clients:-
|
||||
- Define tags in `Readme.md` for each client input files. Use the `batch` autorest option to create the two clients:-
|
||||
|
||||
```yaml
|
||||
batch:
|
||||
- tag-client1
|
||||
- tag-client2
|
||||
- tag-client1
|
||||
- tag-client2
|
||||
```
|
||||
|
||||
- For each individual clients, follow the previous guidance on single clients. You may have options specific to only one tag for one client.
|
||||
- For each individual clients, follow the previous guidance on single clients. You may have options specific to only one tag for one client.
|
||||
|
||||
## Rename a model name
|
||||
|
||||
|
|
@ -121,10 +130,10 @@ Just rename the model name directly in Swagger. Since this name is not use in JS
|
|||
Since attribute name are used in JSON serialization, the recommendation will vary depending on the status of your API.
|
||||
|
||||
- If you API is still in design or in preview, we encourage to update the RestAPI server implementation to the new name, and then update the Swagger accordingly.
|
||||
- If you API is GA and changing the server name would be a breaking change, we need to declare a mapping between the SDK name and the JSON name. It's achieved with the extensions
|
||||
`x-ms-client-name` :
|
||||
- If you API is GA and changing the server name would be a breaking change, we need to declare a mapping between the SDK name and the JSON name. It's achieved with the extensions
|
||||
`x-ms-client-name` :
|
||||
|
||||
``` json
|
||||
```json
|
||||
"ModelNAme": {
|
||||
"description": "This model is very helpful.",
|
||||
"properties": {
|
||||
|
|
@ -143,6 +152,7 @@ You will get this feedback if your operation is returning a list of objects. Con
|
|||
The full documentation for pageable is available here: https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-pageable
|
||||
|
||||
At a glance:
|
||||
|
||||
- Add `x-ms-pageable` node to your operation definition.
|
||||
- Make sure your return schema is an array of T (T could be anything).
|
||||
- `nextLinkName` can be `null` if your service do not support paging yet, otherwise should be the JSON key where the next link is (usually `nextLink`).
|
||||
|
|
@ -167,16 +177,18 @@ You will get this feedback if your operation is a Long Running Operation (LRO),
|
|||
"operationId": "CreateVirtualMachine",
|
||||
"x-ms-long-running-operation": true
|
||||
```
|
||||
|
||||
|
||||
For most of the time, _there is no additional information to provide_ as the language runtime will auto-detect what polling mechanism to use.
|
||||
|
||||
|
||||
Some options can be configured with the node ["x-ms-long-running-operation-options"](https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-long-running-operation-options):
|
||||
- "final-state-via": Is here to prematuraly stop the polling in case your service do not respect the LRO correctly. _Do not use this option if you think your service respects the LRO guidelines, as you could break SDK_. In doubt about this option, please talk to the RestAPI stewardship board.
|
||||
|
||||
- "final-state-via": Is here to prematuraly stop the polling in case your service do not respect the LRO correctly. _Do not use this option if you think your service respects the LRO guidelines, as you could break SDK_. In doubt about this option, please talk to the RestAPI stewardship board.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"x-ms-long-running-operation": true,
|
||||
"x-ms-long-running-operation-options": {
|
||||
"final-state-via": "location"
|
||||
}
|
||||
```
|
||||
```
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче