[Hub Generated] Review request for Microsoft.AlertsManagement to add version preview/2023-04-01-preview #22849
Conversation
…w/2023-01-01-preview to version 2023-04-01-preview
|
Hi, @meydand Thanks for your PR. I am workflow bot for review process. Here are some small tips. Any feedback about review process or workflow bot, pls contact swagger and tools team. vscswagger@microsoft.com |
Swagger Validation Report
|
| compared tags (via openapi-validator v2.0.0) | new version | base version |
|---|---|---|
| package-2021-08 | package-2021-08(15a0fef) | package-2021-08(main) |
[must fix]The following errors/warnings are introduced by current PR:
| Rule | Message | Related RPC [For API reviewers] |
|---|---|---|
|
The path for 'put' operation must be under a subscription and resource group. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L37 |
RPC-Put-V1-01 |
|
The resource name parameter 'managementGroupName' should be defined with a 'pattern' restriction. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L37 |
RPC-Uri-V1-05 |
|
The resource name parameter 'managementGroupName' should be defined with a 'pattern' restriction. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L232 |
RPC-Uri-V1-05 |
|
The top-level resource 'TenantActivityLogAlertResource' does not have list by subscription operation, please add it. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L308 |
RPC-Get-V1-05 |
| The response of operation:'TenantActivityLogAlerts_CreateOrUpdate' is defined without 'systemData'. Consider adding the systemData to the response. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L38 |
||
| The response of operation:'TenantActivityLogAlerts_Get' is defined without 'systemData'. Consider adding the systemData to the response. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L87 |
||
| The response of operation:'TenantActivityLogAlerts_Update' is defined without 'systemData'. Consider adding the systemData to the response. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L155 |
||
| Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L370 |
||
| Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum. Location: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json#L508 |
️❌Avocado: 3 Errors, 1 Warnings failed [Detail]
| Rule | Message |
|---|---|
|
The default tag should contain all APIs. The API path /providers/Microsoft.Management/managementGroups/{}/providers/Microsoft.AlertsManagement/tenantActivityLogAlerts/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/alertsmanagement/resource-manager/readme.md json: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json |
|
The default tag should contain all APIs. The API path /providers/Microsoft.AlertsManagement/tenantActivityLogAlerts is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/alertsmanagement/resource-manager/readme.md json: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json |
|
The default tag should contain all APIs. The API path /providers/Microsoft.Management/managementGroups/{}/providers/Microsoft.AlertsManagement/tenantActivityLogAlerts is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/alertsmanagement/resource-manager/readme.md json: Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json |
| The default tag contains multiple API versions swaggers. readme: specification/alertsmanagement/resource-manager/readme.md tag: specification/alertsmanagement/resource-manager/readme.md#tag-package-2023-03 |
️️✔️ApiReadinessCheck succeeded [Detail] [Expand]
️⚠️~[Staging] ServiceAPIReadinessTest: 0 Warnings warning [Detail]
API Test is not triggered due to precheck failure. Check pipeline log for details.
️️✔️SwaggerAPIView succeeded [Detail] [Expand]
️️✔️CadlAPIView succeeded [Detail] [Expand]
️️✔️ModelValidation succeeded [Detail] [Expand]
Validation passes for ModelValidation.
️️✔️SemanticValidation succeeded [Detail] [Expand]
Validation passes for SemanticValidation.
️️✔️PoliCheck succeeded [Detail] [Expand]
Validation passed for PoliCheck.
️️✔️PrettierCheck succeeded [Detail] [Expand]
Validation passes for PrettierCheck.
️️✔️SpellCheck succeeded [Detail] [Expand]
Validation passes for SpellCheck.
️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
Validation passes for Lint(RPaaS).
️️✔️CadlValidation succeeded [Detail] [Expand]
Validation passes for CadlValidation.
️️✔️PR Summary succeeded [Detail] [Expand]
Validation passes for Summary.
Swagger Generation Artifacts
|
Generated ApiView
|
|
Hi @meydand, Your PR has some issues. Please fix the CI sequentially by following the order of
|
|
Hi, @meydand your PR are labelled with WaitForARMFeedback. A notification email will be sent out shortly afterwards to notify ARM review board(armapireview@microsoft.com). |
|
This PR introduces a new Resource Type - ‘Microsoft.AlertsManagement/TenantActivityLogAlerts’. ‘Microsoft.Insights/ActivityLogAlerts’ are alerts that monitors the customers’ activity logs. |
| "webhookProperties": { | ||
| "type": "object", | ||
| "description": "the dictionary of custom properties to include with the post operation. These data are appended to the webhook payload.", | ||
| "additionalProperties": { |
There was a problem hiding this comment.
ARM recommends against the use of the additionalProperties/empty/unschematized object pattern. ARM favors stronger typing wherever possible because it allows all consumers of your API to reason about it. This has benefits for everyone that interacts with your API including basic infrastructure, other Azure features, SDK owners, and customers. Unschematized objects are essentially API contracts that bypass Azure versioning infrastructure.
For example, customers will not be able to manage these objects using Azure Policy, or query them using ARG, both of which are standard Azure features. Customers expect to be able to use all common Azure features against all of their resources.
Generally, this pattern should only be used when needed and the object properties are dynamic, unknown, or user defined. Ref: https://armwiki.azurewebsites.net/api_contracts/guidelines/openapi.html#oapi032-only-use-additionalproperties-when-the-object-properties-are-dynamic-unknown-or-user-defined.
There was a problem hiding this comment.
This resource type is an extension resource flavor of microsoft.insights/activityLogAlerts - to make customers use alerts without owning a subscription.
Therefore, we would like the payload to be similar to it.
More specifically, identical to this API version https://github.com/Azure/azure-rest-api-specs/pull/22575/files
There was a problem hiding this comment.
I'm still not sure I understand what you want here. Do you mean that you want this property bag to be the same as activityLogAlerts' one, which already does webhookProeprties and actionProperties this way, as 'additionalProperties'?
| }, | ||
| "actionProperties": { | ||
| "type": "object", | ||
| "additionalProperties": { |
There was a problem hiding this comment.
Again - aligning with ActivityLogAlerts
There was a problem hiding this comment.
Is this an existing public REST API you're referring to? Link? @meydand
There was a problem hiding this comment.
I see, referenced above.
| }, | ||
| "enabled": { | ||
| "description": "Indicates whether this Activity Log Alert rule is enabled. If an Activity Log Alert rule is not enabled, then none of its actions will be activated.", | ||
| "type": "boolean", |
There was a problem hiding this comment.
ARM recommends string enums over boolean. Generally enums make better properties than booleans. They are more descriptive and flexible while being easier for customers to discover, understand and use. Ref: https://armwiki.azurewebsites.net/rp_onboarding/process/api_review_best_practices.html?q=boolean#common-issues-found-in-review. They allow values other than just true/false and support description strings. Even if you only ever want two values, you can have a string enum with True/False (or Enabled/Disabled, etc.).
There was a problem hiding this comment.
This resource type is an extension resource flavor of microsoft.insights/activityLogAlerts - to make customers use alerts without owning a subscription.
Therefore, we would like the payload to be similar to it.
More specifically, identical to this API version https://github.com/Azure/azure-rest-api-specs/pull/22575/files
...e-manager/Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json
Outdated
Show resolved
Hide resolved
...e-manager/Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json
Outdated
Show resolved
Hide resolved
...e-manager/Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json
Outdated
Show resolved
Hide resolved
| "read", | ||
| "create" | ||
| ] | ||
| }, |
There was a problem hiding this comment.
Interesting. Does it need the global location because its a tracked resource?
| "AzureResource": { | ||
| "description": "An Azure resource object.", | ||
| "x-ms-azure-resource": true, | ||
| "type": "object", |
There was a problem hiding this comment.
Instead of defining your own AzureResource its usually recommended to inherit ProxyResource or TrackedResource from common-types.
There was a problem hiding this comment.
I tried using 'Tracked Resource' at first but I got multiple validation errors for not offering a 'list' operation in the resource group etc. Will you be able to approve despite these errors or should I use anything else? My resource is configured as an extension - and will be allowed to be used as an extension of a management group only - therefore can be listed on a management group only
There was a problem hiding this comment.
Probably ProxyResource would be the better fit then?
EIther way, if you still have errors about list by resoruce group, I think we could suppress them.
...e-manager/Microsoft.AlertsManagement/preview/2023-04-01-preview/TenantActivityLogAlerts.json
Show resolved
Hide resolved
| "read", | ||
| "create" | ||
| ] | ||
| }, |
There was a problem hiding this comment.
(I'm actually a little confused about the value of a 'location' property in this case. Isn't 'global' not significantly different from having no location? Is it being used for routing somehow?)
There was a problem hiding this comment.
Activity Log Alerts Resource provider is a global service - therefore the expected location will always 'global' - and it will always be routed to the same traffic manager
|
this PR does not change the default tag, therefore ignoring the avocado failure |
|
the linter issues are false alarms because the added resource is under mgmt group instead of subscription or resource group |
|
Since this PR does not change the default tag, SDK breaking changes should exist before this PR |
…version preview/2023-04-01-preview (Azure#22849) * Adds base for updating Microsoft.AlertsManagement from version preview/2023-01-01-preview to version 2023-04-01-preview * Updates readme * Updates API version in new specs and examples * Add TenantActivityLogAlerts Resource type * Prettier * Align with ALA * Fix issues * Prettier * Fix param * fix PR comments --------- Co-authored-by: meydand <t-meday@microsoft.com> Co-authored-by: Meydan Dayan <meday@microsoft.com>
This is a PR generated at OpenAPI Hub. You can view your work branch via this link.
ARM API Information (Control Plane)
Azure 1st Party Service can try out the Shift Left experience to initiate API design review from ADO code repo. If you are interested, may request engineering support by filling in with the form https://aka.ms/ShiftLeftSupportForm.
Changelog
Add a changelog entry for this PR by answering the following questions:
Contribution checklist (MS Employees Only):
If any further question about AME onboarding or validation tools, please view the FAQ.
ARM API Review Checklist
Otherwise your PR may be subject to ARM review requirements. Complete the following:
Check this box if any of the following apply to the PR so that the label "ARMReview" and "WaitForARMFeedback" will be added by bot to kick off ARM API Review. Missing to check this box in the following scenario may result in delays to the ARM manifest review and deployment.
-[ ] To review changes efficiently, ensure you copy the existing version into the new directory structure for first commit and then push new changes, including version updates, in separate commits. You can use OpenAPIHub to initialize the PR for adding a new version. For more details refer to the wiki.
Ensure you've reviewed following guidelines including ARM resource provider contract and REST guidelines. Estimated time (4 hours). This is required before you can request review from ARM API Review board.
If you are blocked on ARM review and want to get the PR merged with urgency, please get the ARM oncall for reviews (RP Manifest Approvers team under Azure Resource Manager service) from IcM and reach out to them.
Breaking Change Review Checklist
If you have any breaking changes as defined in the Breaking Change Policy, request approval from the Breaking Change Review Board.
Action: to initiate an evaluation of the breaking change, create a new intake using the template for breaking changes. Additional details on the process and office hours are on the Breaking Change Wiki.
NOTE: To update API(s) in public preview for over 1 year (refer to Retirement of Previews)
Please follow the link to find more details on PR review process.