azure-rest-api-specs
azure-rest-api-specs copied to clipboard
Published
20 hours ago •
Azure
Azure
Add API Version for new Purview Data Plane API 2023-12-01-preview
Data Plane API - Pull Request
API Info: The Basics
Most of the information about your service should be captured in the issue that serves as your API Spec engagement record.
- Link to API Spec engagement record issue:
Is this review for (select one):
- [x] a private preview
- [ ] a public preview
- [ ] GA release
Change Scope
This section will help us focus on the specific parts of your API that are new or have been modified.
Please share a link to the design document for the new APIs, a link to the previous API Spec document (if applicable), and the root paths that have been updated.
- Design Document:
- Previous API Spec Doc:
- Updated paths:
Viewing API changes
For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.
Suppressing failures
If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the Swagger-Suppression-Process to get approval.
❔Got questions? Need additional info?? We are here to help!
Contact us!
The Azure API Review Board is dedicated to helping you create amazing APIs. You can read about our mission and learn more about our process on our wiki.
- 💬 Teams Channel
Click here for links to tools, specs, guidelines & other good stuff
Tooling
- Open API validation tools were run on this PR. Go here to see how to fix errors
- Spectral Linting
- Open API Hub
Guidelines & Specifications
Helpful Links
Checks stuck in `queued` state?
If the PR CI checks appear to be stuck in `queued` state, please add a comment with contents `/azp run`. This should result in a new comment denoting a `PR validation pipeline` has started and the checks should be updated after few minutes.
Next Steps to Merge
Next steps that must be taken to merge this PR:- ❌ Your PR requires an API stewardship board review as it introduces a new API version (label:
new-api-version). Schedule the review by following aka.ms/azsdk/onboarding/restapischedule. - ❌ The required check named
Swagger PrettierCheckhas failed. Refer to the check in the PR's 'Checks' tab for details on how to fix it
![openapi-pipeline-app[bot] avatar](https://avatars.githubusercontent.com/in/65541?v=4 "Published by a pub.dev verified publisher"){kind=small}
Swagger Validation Report
️️✔️BreakingChange succeeded [Detail] [Expand]
There are no breaking changes.
️❌Breaking Change(Cross-Version): 2 Errors, 0 Warnings failed [Detail]
The following breaking changes are detected by comparison with the latest stable version:
| Rule | Message |
|---|---|
|
"new":"https://github.com/Azure/azure-rest-api-specs/blob/fdd97d50be1db4f7e3c9173dcc56d5ba121ba9b2/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json", "old":"https://github.com/Azure/azure-rest-api-specs/blob/main/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/stable/2023-09-01/purviewdatamap.json", "details":"Breaking change detector (OAD) invoked AutoRest. AutoRest threw a runtime error. First 6 lines of stack trace follow, indexed. First line should contain AutoRest command line invocation details. Second line should contain the main message reported by AutoRest. ==================== 1: Command failed: node "/mnt/vss/_work/_tasks/AzureApiValidation_5654d05d-82c1-48da-ad8f-161b817f6d41/0.0.90/common/temp/node_modules/.pnpm/@[email protected]/node_modules/autorest/dist/app.js" --v2 --input-file=specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json --output-artifact=swagger-document.json --output-artifact=swagger-document.map --output-file=new --output-folder=/tmp -------------------- 2: ERROR: Schema violation: No enum match for: operation-location -------------------- 3: - file:///mnt/vss/_work/1/azure-rest-api-specs/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json:1710:10 ($.paths["/entity/bulk/delete"].delete["x-ms-long-running-operation-options"]["final-state-via"]) -------------------- 4: FATAL: swagger-document/individual/schema-validator - FAILED -------------------- 5: FATAL: Error: [OperationAbortedException] Error occurred. Exiting. -------------------- 6: Process() cancelled due to exception : [OperationAbortedException] Error occurred. Exiting. --------------------" |
The following breaking changes are detected by comparison with the latest preview version:
| Rule | Message |
|---|---|
|
"new":"https://github.com/Azure/azure-rest-api-specs/blob/fdd97d50be1db4f7e3c9173dcc56d5ba121ba9b2/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json", "old":"https://github.com/Azure/azure-rest-api-specs/blob/main/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-10-01-preview/purviewdatamap.json", "details":"Breaking change detector (OAD) invoked AutoRest. AutoRest threw a runtime error. First 6 lines of stack trace follow, indexed. First line should contain AutoRest command line invocation details. Second line should contain the main message reported by AutoRest. ==================== 1: Command failed: node "/mnt/vss/_work/_tasks/AzureApiValidation_5654d05d-82c1-48da-ad8f-161b817f6d41/0.0.90/common/temp/node_modules/.pnpm/@[email protected]/node_modules/autorest/dist/app.js" --v2 --input-file=/mnt/vss/_work/1/cross-version-c93b354fd9c14905bb574a8834c4d69b/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-10-01-preview/purviewdatamap.json --output-artifact=swagger-document.json --output-artifact=swagger-document.map --output-file=old --output-folder=/tmp -------------------- 2: ERROR: Schema violation: No enum match for: operation-location -------------------- 3: - file:///mnt/vss/_work/1/cross-version-c93b354fd9c14905bb574a8834c4d69b/specification/purview/data-plane/Azure.Analytics.Purview.DataMap/preview/2023-10-01-preview/purviewdatamap.json:1620:10 ($.paths["/entity/bulk/delete"].delete["x-ms-long-running-operation-options"]["final-state-via"]) -------------------- 4: FATAL: swagger-document/individual/schema-validator - FAILED -------------------- 5: FATAL: Error: [OperationAbortedException] Error occurred. Exiting. -------------------- 6: Process() cancelled due to exception : [OperationAbortedException] Error occurred. Exiting. --------------------" |
️️✔️CredScan succeeded [Detail] [Expand]
There is no credential detected.
️❌LintDiff: 0 Errors, 41 Warnings failed [Detail]
| Compared specs (v2.2.0) | new version | base version |
|---|---|---|
| package-preview-2023-12 | package-preview-2023-12(fdd97d5) | default(main) |
[must fix]The following errors/warnings are introduced by current PR:
Only 30 items are listed, please refer to log for more details.
| Rule | Message | Related RPC [For API reviewers] |
|---|---|---|
| :warning: RequestBodyOptional | The body parameter is not marked as required. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1766 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1782 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1793 |
|
| :warning: ErrorResponse | Error response schema should contain an object property named error.Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1795 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1822 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1836 |
|
| :warning: ErrorResponse | Error response schema should contain an object property named error.Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1838 |
|
| :warning: PutRequestResponseScheme | A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'Type_ReplaceIcon' Request Model: 'parameters[0].schema' Response Model: 'responses[200].schema' Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1846 |
|
| :warning: OperationId | OperationId for put method should contain 'Create' or 'Update' Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1851 |
|
| :warning: PutInOperationName | 'PUT' operation 'Type_ReplaceIcon' should use method name 'Create'. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1851 |
|
| :warning: RequestBodyOptional | The body parameter is not marked as required. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1861 |
|
| :warning: PathParameterSchema | Path parameter should specify a maximum length (maxLength) and characters allowed (pattern). Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1869 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1877 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1888 |
|
| :warning: ErrorResponse | Error response schema should contain an object property named error.Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1890 |
|
| :warning: GetInOperationName | 'GET' operation 'Type_DownloadIcon' should use method name 'Get' or Method name start with 'List'. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1901 |
|
| :warning: OperationId | OperationId for get method should contain 'Get' or 'list' Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1901 |
|
| :warning: PathParameterSchema | Path parameter should specify a maximum length (maxLength) and characters allowed (pattern). Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1911 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1919 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1931 |
|
| :warning: ErrorResponse | Error response schema should contain an object property named error.Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1933 |
|
| :warning: PathParameterSchema | Path parameter should specify a maximum length (maxLength) and characters allowed (pattern). Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1951 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1959 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1967 |
|
| :warning: ErrorResponse | Error response schema should contain an object property named error.Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L1969 |
|
| :warning: PaginationResponse | Operation might be pageable. Consider adding the x-ms-pageable extension. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L4534 |
|
| :warning: ParameterDescription | Parameter should have a description. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L4546 |
|
| :warning: RequestBodyOptional | The body parameter is not marked as required. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L4546 |
|
| :warning: VersionPolicy | 'api-version' should be a required parameter Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L4553 |
|
| :warning: ErrorResponse | Error response should contain a x-ms-error-code header. Location: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L4564 |
The following errors/warnings exist before current PR submission:
Only 30 items are listed, please refer to log for more details.
️️✔️Avocado succeeded [Detail] [Expand]
Validation passes for Avocado.
️️✔️SwaggerAPIView succeeded [Detail] [Expand]
️️✔️TypeSpecAPIView succeeded [Detail] [Expand]
️❌ModelValidation: 2 Errors, 0 Warnings failed [Detail]
| Rule | Message |
|---|---|
|
Additional properties not allowed: businessAttributeDefs Url: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L5059:23 ExampleUrl: preview/2023-12-01-preview/examples/Type_List_With_FullName.json#L244:38 |
|
Additional properties not allowed: businessAttributeDefs Url: Azure.Analytics.Purview.DataMap/preview/2023-12-01-preview/purviewdatamap.json#L5059:23 ExampleUrl: preview/2023-12-01-preview/examples/Type_List_With_FullName.json#L244:38 |
️️✔️SemanticValidation succeeded [Detail] [Expand]
Validation passes for SemanticValidation.
️️✔️PoliCheck succeeded [Detail] [Expand]
Validation passed for PoliCheck.
️️✔️SpellCheck succeeded [Detail] [Expand]
Validation passes for SpellCheck.
️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
Validation passes for Lint(RPaaS).
️️✔️PR Summary succeeded [Detail] [Expand]
Validation passes for Summary.
️️✔️Automated merging requirements met succeeded [Detail] [Expand]
Swagger Generation Artifacts
️️✔️ApiDocPreview succeeded [Detail] [Expand]
Please click here to preview with your @microsoft account.
️️✔️SDK Breaking Change Tracking succeeded [Detail] [Expand]
Breaking Changes Tracking
️❌ azure-sdk-for-net-track2 failed [Detail]
- Only show 20 items here, please refer to log for details.
❌Failed [Logs] Generate from 7eee3684cb93fc965a052d67f26dce65f4e141fe. SDK Automation 14.0.0cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m 714 | [0m [36;1mGeneratePackage -projectFolder $projectFolder -sdkRootPath $s[0m …[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m | [31;1m ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m | [31;1mFailed to generate sdk artifact[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1mGeneratePackage: [0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:714[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1mLine |[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m 714 | [0m [36;1mGeneratePackage -projectFolder $projectFolder -sdkRootPath $s[0m …[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m | [31;1m ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m | [31;1mFailed to generate sdk. exit code: False[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1mGet-ChildItem: [0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:807[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1mLine |[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m 807 | [0m … rtifacts += [36;1mGet-ChildItem $artifactsPath -Filter *.nupkg -exclude *.s[0m …[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m | [31;1m ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m | [31;1mCannot find path[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m[31;1m[36;1m | [31;1m'/mnt/vss/_work/1/s/azure-sdk-for-net/artifacts/packages/Debug/' because[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m[31;1m[36;1m[31;1m[36;1m | [31;1mit does not exist.[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1mGeneratePackage: [0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:714[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1mLine |[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m 714 | [0m [36;1mGeneratePackage -projectFolder $projectFolder -sdkRootPath $s[0m …[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m | [31;1m ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[0m cmderr [Invoke-GenerateAndBuildV2.ps1] [31;1m[0m[36;1m[36;1m[0m[36;1m[0m[36;1m[31;1m[31;1m[36;1m | [31;1mFailed to generate sdk artifact[0m
❌Azure.Analytics.Purview.Account [View full logs] [Preview SDK Changes]info [Changelog]
❌Azure.Analytics.Purview.Administration [View full logs] [Preview SDK Changes]info [Changelog]
❌Azure.Analytics.Purview.Catalog [View full logs] [Preview SDK Changes]info [Changelog]
❌Azure.Analytics.Purview.Scanning [View full logs] [Preview SDK Changes]info [Changelog]
❌Azure.Analytics.Purview.Sharing [View full logs] [Preview SDK Changes]info [Changelog]
❌Azure.Analytics.Purview.Workflows [View full logs] [Preview SDK Changes]info [Changelog]
Generated ApiView
| Language | Package Name | ApiView Link |
|---|---|---|
| Swagger | Azure.Analytics.Purview.DataMap | https://apiview.dev/Assemblies/Review/17f9d062cae340bd9a831088c8b58219?revisionId=5de8702861704b57b4fdf8308c1385fb |
Hi @xuyan3! For review efficiency consideration, when creating a new API version, it is required to place API specs of the base version in the first commit, and push new version updates into successive commits. You can use OpenAPIHub to initialize the PR for adding a new version.
For more details refer to the wiki.
![openapi-workflow-bot[bot] avatar](https://avatars.githubusercontent.com/in/81125?v=4 "Published by a pub.dev verified publisher"){kind=small}
I left a few comments in the APIView, but to recap the review meeting:
Discuss amongst your team how to better map settings and typeDefs. Reviewers had trouble understanding it so customers likely will as well. It seems these are two separate resources collections, so it might make sense to have /typeDefs (or similar, which you already have) and /settings, each with their own CRUD operations as appropriate. It might mean that customers using settings first have to create settings to refer to them in typeDefs, but that order of operations is not uncommon across many Azure services.
In general, use PATCH to create or update (we typically call these operationIds "CreateOrUpdate_{ResourceType}", in fact).
For icons, there should be one collection - /types/icons - on which you have CRUD operations:
/types/icons
- GET: List_Icons
- POST: Create_Icon - only if the customer doesn't control the ID/name, which I believe you said they can control it so you probably won't have this
/types/icons/{name}
- PATCH: CreateOrUpdate_Icon
- GET: Get_Icon
- DELETE: Delete_Icon
For the type namespace changes, just always include the new
fullTypeNamewithout having customers pass?withFullTypeName=true. Only support that query parameter where needed i.e., where you return an array of eithertypeNameorfullTypeName.
Thanks Heaths for help with API review. For Icon APIs, we updated paths using plural. But after internal discussions, we decided to go with PUT/POST instead of PATCH. Mainly because icon is a rather simple scenario and we want to keep users clear for whether they are creating or replacing an icon, without worrying about overwrite.
Hi, @xuyan3. Your PR has no update for 14 days and it is marked as stale PR. If no further update for over 14 days, the bot will close the PR. If you want to refresh the PR, please remove no-recent-activity label.
![microsoft-github-policy-service[bot] avatar](https://avatars.githubusercontent.com/in/95686?v=4 "Published by a pub.dev verified publisher"){kind=small}
Hi, @xuyan3. The PR will be closed since the PR has no update for 28 days. If you still need the PR review to proceed, please reopen it and @ mention PR assignee.