[Azure Maps] Async Batch API schema change by chcmsft · Pull Request #29284 · Azure/azure-rest-api-specs

chcmsft · 2024-05-31T04:23:11Z

Change

change the AsyncBatchManagement API version from 2024-04-01-preview to 2024-10-01-preview
change the Search API version from 2024-04-01-preview to 2024-10-01-preview
add new Route API version 2024-10-01-preview
remove Route API version 2024-04-01-preview
remove route directions async batch api from both 2024-05-01-preview and 2024-06-01 preview api version
object schema change of AsyncBatchOperation object in AsyncBatchManagement API
request body change of async batch APIs in both Search 2024-10-01-preview and Route 2024-10-01-preview

API version change

We change the api version of AsyncBatchManagement/Route/Search from 2024-04-01-preview to 2024-10-01-preview because of the release plan. The target is to release the async batch APIs with api version 2024-10-01-preview. Thus, Route 2024-05-01-preview and 2024-06-01-preview don't contain the async batch route direction API anymore and need to remove the async batch route directions api from both 2024-05-01-preview and 2024-06-01-preview api version.

Major API Change

Request body of geocoding async batch, reverse geocoding async batch, route directions async batch

We change the design from processing one input blob and generate one output blob to processing multiple input blobs and transform them into multiple output blobs.
Thus, the inputBlobUrl is replaced by inputFolderPath. the outputStorageUrl is replaced by outputFolderPath.

original request body

{
    "inputBlobUrl": "https://exampleinputstorage.blob.core.windows.net/asyncbatch/reverseGeocodingBatchItems.json",
    "outputStorageUrl": "https://exampleoutputstorage.blob.core.windows.net/",
    "msiClientId": "12345678-abcd-1234-efgh-12345678ijkl"
}

new request body

{
    "inputFolderPath": "https://exampleinputstorage.blob.core.windows.net/asyncbatch/input/",
    "outputFolderPath": "https://exampleoutputstorage.blob.core.windows.net/asyncbatch/output/",
    "msiClientId": "12345678-abcd-1234-efgh-12345678ijkl"
}

AsyncBatchManagement Get Operation API response schema change

due to the requirement change from processing single blob to multiple blobs, I tweak the operation status response according to the request body change above.

original

{
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "Geocode",
    "inputBlobUrl": "https://examplestorage.blob.core.windows.net/asyncbatch/geocodingBatchItems.json",
    "outputStorageUrl": "https://exampleoutputstorage.blob.core.windows.net/",
    "msiClientId": "87654321-abcd-1234-efgh-12345678ijkl",
    "createdDateTime": "2023-01-01T00:00:00Z",
    "lastActionDateTime": "2023-01-01T00:00:00Z",
    "percentComplete": 0,
    "totalItemCount": 1000,
    "status": "NotStarted"
}

new

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "kind": "Geocode",
    "inputFolderPath": "https://examplestorage.blob.core.windows.net/asyncbatch/input/",
    "outputFolderPath": "https://exampleoutputstorage.blob.core.windows.net/asyncbatch/output/",
    "msiClientId": "87654321-abcd-1234-efgh-12345678ijkl",
    "createdDateTime": "2023-01-01T00:00:00Z",
    "lastActionDateTime": "2023-01-01T00:00:00Z",
    "progress": "0/10",
    "status": "NotStarted"
}

Note

These APIs are not published yet. Thus, no breaking change concern.

Click here to open a PR for a Data Plane API.

openapi-pipeline-app · 2024-05-31T04:23:14Z

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

openapi-pipeline-app · 2024-05-31T04:23:15Z

Swagger Validation Report

️❌BreakingChange: 10 Errors, 0 Warnings failed [Detail]

Compared specs (v0.10.9)	new version	base version
asyncBatchManagement.json	2024-04-01-preview(8210c43)	2024-04-01-preview(main)

Rule	Message
`❌` 1007 - RemovedClientParameter	The new version is missing a client parameter that was found in the old version. Was 'OperationId' removed or renamed? New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L60:3 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L60:3
`❌` 1009 - RemovedRequiredParameter	The required parameter 'operationId' was removed in the new version. Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L103:9
`❌` 1010 - AddingRequiredParameter	The required parameter 'id' was added in the new version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L103:9
`❌` 1033 - RemovedProperty	The new version is missing a property found in the old version. Was 'operationId' renamed or removed? New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7
`❌` 1033 - RemovedProperty	The new version is missing a property found in the old version. Was 'operationType' renamed or removed? New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7
`❌` 1034 - AddedRequiredProperty	The new version has new required property 'id' that was not found in the old version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7
`❌` 1034 - AddedRequiredProperty	The new version has new required property 'kind' that was not found in the old version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L196:7
`❌` 1034 - AddedRequiredProperty	The new version has new required property 'id, kind' that was not found in the old version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L114:13 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L114:13
`❌` 1034 - AddedRequiredProperty	The new version has new required property 'id, kind' that was not found in the old version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L338:11 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L338:11
`❌` 1034 - AddedRequiredProperty	The new version has new required property 'id, kind' that was not found in the old version. New: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L193:5 Old: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L193:5

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️CredScan succeeded [Detail] [Expand]

There is no credential detected.

️⚠️LintDiff: 2 Warnings warning [Detail]

Compared specs (v2.2.2)	new version	base version
package-preview-2024-04	package-preview-2024-04(8210c43)	package-preview-2024-04(main)

[must fix]The following errors/warnings are introduced by current PR:

Rule	Message	Related RPC [For API reviewers]
⚠️ ErrorResponse	Error schema should define `code` and `message` properties as required. Location: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L120
⚠️ ErrorResponse	The `error` property in the error response schema should be required. Location: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L120

The following errors/warnings exist before current PR submission:

Rule	Message
⚠️ ErrorResponse	Error schema should define `code` and `message` properties as required. Location: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L160
⚠️ ErrorResponse	The `error` property in the error response schema should be required. Location: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L160
⚠️ AvoidNestedProperties	Consider using x-ms-client-flatten to provide a better end user experience Location: AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json#L302

️️✔️Avocado succeeded [Detail] [Expand]

Validation passes for Avocado.

️️✔️SwaggerAPIView succeeded [Detail] [Expand]

️️✔️TypeSpecAPIView 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.

️️✔️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]

_{Posted by Swagger Pipeline | How to fix these errors?}

openapi-pipeline-app · 2024-05-31T04:23:15Z

Swagger Generation Artifacts

️️✔️ApiDocPreview succeeded [Detail] [Expand]

 Please click here to preview with your @microsoft account.

_{Posted by Swagger Pipeline | How to fix these errors?}

openapi-pipeline-app · 2024-05-31T04:23:16Z

Generated ApiView

Language	Package Name	ApiView Link
Swagger	AsyncBatchManagement	https://apiview.dev/Assemblies/Review/f86e0470c79f4026abe33303866b1dfd?revisionId=dffb03ca68b24b6599d5583e90158f10
Swagger	Route	https://apiview.dev/Assemblies/Review/46fc96bf83a8468da2623389b47566b4?revisionId=68d2e8e8aab647ecb31587ad2cc24ca7
Swagger	Search	https://apiview.dev/Assemblies/Review/30ba16cfc8324624ae002a76347faac0?revisionId=a7353ca29e3e4efd890f5ee64edb21d4

weidongxu-microsoft

You need to pass breaking changes review.

chcmsft · 2024-05-31T05:24:42Z

@mikekistler @JeffreyRichter
Please help to review this PR.
The change is made due to the review comment from this PR review.

We want to make our API schema consistent by adopting kind and id to status monitor API.
This is not a breaking change since these APIs are not published yet.

mikekistler

Looks good! 👍

chcmsft · 2024-06-03T04:18:41Z

@mikekistler
Thanks for your approval! If it's all good to you, can you help to remove the breakingChangedReviewRequired tag and merge this PR?

chcmsft · 2024-07-18T07:46:32Z

@weidongxu-microsoft
The API schema is changed due to spec change. Can you help to review the new changes?

winest · 2024-09-04T07:53:49Z

Changes:

Change api-version from 2024-10-01-preview to 2024-07-01-preview to align with all azure maps service in this semester
Fix naming of inputFolderPath/outputFolderPath to inputContainerUri/outputContainerUri based on review comment
Fix descriptions based on review comment
Rebase on latest Azure/main branch

1. Sort swagger 2. Add 2024-04-01-preview back

…n in example

…utContainerUri and outputContainerUri

…are already in main branch

… to 2024-10-01-preview

…eview and 2024-06-01-preview as they are already in main

microsoft-github-policy-service · 2024-11-25T00:54:33Z

Hi, @chcmsft. 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 · 2024-12-09T13:17:33Z

Hi, @chcmsft. 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.

chcmsft requested a review from a team as a code owner May 31, 2024 04:23

chcmsft requested review from DominikMe and MushMal and removed request for a team May 31, 2024 04:23

AzureRestAPISpecReview added BreakingChangeReviewRequired <valid label in PR review process>add this label when breaking change review is required data-plane labels May 31, 2024

weidongxu-microsoft approved these changes May 31, 2024

View reviewed changes

Comment thread ...on/maps/data-plane/AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json Outdated

mikekistler approved these changes May 31, 2024

View reviewed changes

Comment thread ...on/maps/data-plane/AsyncBatchManagement/preview/2024-04-01-preview/asyncBatchManagement.json Outdated

JeffreyRichter added the BreakingChange-Approved-BugFix Changes are to correct the REST API definition to correctly describe service behavior label Jun 5, 2024

microsoft-github-policy-service Bot added the no-recent-activity There has been no recent activity on this issue. label Jun 24, 2024

weidongxu-microsoft added the APIStewardshipBoard-SignedOff The Azure API Stewardship team has reviewed and approved the changes. label Jun 24, 2024

microsoft-github-policy-service Bot removed the no-recent-activity There has been no recent activity on this issue. label Jun 24, 2024

microsoft-github-policy-service Bot added no-recent-activity There has been no recent activity on this issue. and removed no-recent-activity There has been no recent activity on this issue. labels Jul 15, 2024

chcmsft force-pushed the users/chihcheng/async-batch-schema-fix branch 3 times, most recently from ad33659 to e1fbfba Compare July 17, 2024 04:05

AzureRestAPISpecReview added the new-api-version label Jul 17, 2024

chcmsft force-pushed the users/chihcheng/async-batch-schema-fix branch 2 times, most recently from a190a28 to 8acc589 Compare July 17, 2024 09:14

koyasu221b added the PublishToCustomers Acknowledgement the changes will be published to Azure customers. label Jul 18, 2024

chcmsft changed the title ~~[Azure Maps] fix the status monitoring API schema~~ [Azure Maps] Async Batch API schema change Jul 18, 2024

chcmsft force-pushed the users/chihcheng/async-batch-schema-fix branch from 98a9f86 to d036d9c Compare July 18, 2024 07:45

winest force-pushed the users/chihcheng/async-batch-schema-fix branch 2 times, most recently from 2dfc596 to 057bb0d Compare September 4, 2024 07:51

microsoft-github-policy-service Bot added no-recent-activity There has been no recent activity on this issue. and removed no-recent-activity There has been no recent activity on this issue. labels Sep 23, 2024

microsoft-github-policy-service Bot added no-recent-activity There has been no recent activity on this issue. labels Oct 14, 2024

Billy Hung added 2 commits October 14, 2024 11:02

[AzureMaps][AsyncBatchPlatform] Refine based on review comments

2b51170

[AzureMaps][AsyncBatchPlatform]

6d3a613

1. Sort swagger 2. Add 2024-04-01-preview back

winest force-pushed the users/chihcheng/async-batch-schema-fix branch from 1d8a840 to 6d3a613 Compare October 14, 2024 05:41

microsoft-github-policy-service Bot removed the no-recent-activity There has been no recent activity on this issue. label Oct 14, 2024

Billy Hung added 5 commits October 14, 2024 14:32

[AzureMaps][AsyncBatchPlatform] Refine description and fix api versio…

fb5a9d9

…n in example

[AzureMaps][AsyncBatchPlatform] Add more detailed description for inp…

0cafe9c

…utContainerUri and outputContainerUri

[AzureMaps][AsyncBatchPlatform] Add 2024-04-01-preview back as there …

5caa33c

…are already in main branch

[AzureMaps][AsyncBatchPlatform] Change async batch 2024-07-01-preview…

e6c6900

… to 2024-10-01-preview

[AzureMaps][AsyncBatchPlatform] Revert change for Route 2024-05-01-pr…

8c3b1c3

…eview and 2024-06-01-preview as they are already in main

koyasu221b added the Do Not Merge label Oct 18, 2024

microsoft-github-policy-service Bot added the no-recent-activity There has been no recent activity on this issue. label Nov 4, 2024

Merge branch 'main' into users/chihcheng/async-batch-schema-fix

323461c

microsoft-github-policy-service Bot removed the no-recent-activity There has been no recent activity on this issue. label Nov 6, 2024

Will Huang added 6 commits November 6, 2024 10:58

suppress typeSpec checking

ec65e72

Fix readme

aa9acbb

add 04-01 back

08f3d29

fix inputContainerUri

f3c232d

Sync with 2024-07-01-preview

311acd3

Remove duplicate key

4968016

microsoft-github-policy-service Bot added the no-recent-activity There has been no recent activity on this issue. label Nov 25, 2024

microsoft-github-policy-service Bot closed this Dec 9, 2024

Conversation

chcmsft commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change

API version change

Major API Change

Request body of geocoding async batch, reverse geocoding async batch, route directions async batch

original request body

new request body

AsyncBatchManagement Get Operation API response schema change

original

new

Note

Uh oh!

openapi-pipeline-app Bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Next Steps to Merge

Uh oh!

openapi-pipeline-app Bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Swagger Validation Report

Uh oh!

openapi-pipeline-app Bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Swagger Generation Artifacts

Uh oh!

openapi-pipeline-app Bot commented May 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generated ApiView

Uh oh!

weidongxu-microsoft left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chcmsft commented May 31, 2024

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chcmsft commented Jun 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chcmsft commented Jul 18, 2024

Uh oh!

winest commented Sep 4, 2024

Uh oh!

microsoft-github-policy-service Bot commented Nov 25, 2024

Uh oh!

microsoft-github-policy-service Bot commented Dec 9, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

chcmsft commented May 31, 2024 •

edited

Loading

openapi-pipeline-app Bot commented May 31, 2024 •

edited

Loading

openapi-pipeline-app Bot commented May 31, 2024 •

edited

Loading

openapi-pipeline-app Bot commented May 31, 2024 •

edited

Loading

openapi-pipeline-app Bot commented May 31, 2024 •

edited

Loading

chcmsft commented Jun 3, 2024 •

edited

Loading