Add AI Face next GA version #31023

Han-msft · 2024-10-15T01:52:49Z

Data Plane API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

Add new api version for face
- Exclude Person Directory, which is not ready for GA.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

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):

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
💌 email

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

Guidelines & Specifications

Helpful Links

Schedule a data plane REST API spec review

Getting help

First, please carefully read through this PR description, from top to bottom.
If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
and https://aka.ms/ci-fix.
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.
If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.

fix #31108

openapi-pipeline-app · 2024-10-15T01:52:52Z

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-10-15T01:52:52Z

Generated ApiView

Language	Package Name	ApiView Link
JavaScript	@azure-rest/ai-vision-face	https://apiview.dev/Assemblies/Review/6d965eeedcb649c4ac1540f49d24a308?revisionId=ae74eed247d441a7a37ddc8d3c1010ae
Python	azure-ai-vision-face	https://apiview.dev/Assemblies/Review/902546534b9f40729eabfbd725b02bff?revisionId=1bf9c955830349138fc7ed0704e74f46
TypeSpec	Face	https://apiview.dev/Assemblies/Review/fd70378562b9470abec3d3f5e04aa38f?revisionId=4e660386a95b490da2e24618cf8b4aa0

mikekistler · 2024-10-19T14:11:24Z

/azp run

azure-pipelines · 2024-10-19T14:11:40Z

Azure Pipelines successfully started running 3 pipeline(s).

mikekistler · 2024-10-22T17:52:21Z

Breaking changes previously reviewed and approved in #29781

mikekistler

Looks good. 👍

specification/ai/Face/routes.persondirectory.tsp

allenjzhang · 2024-10-31T23:03:16Z

specification/ai/Face/models.session.tsp

@@ -166,7 +166,7 @@ union ImageType {
 }

 @doc("The liveness classification for target face.")
-model LivenessOutputsTarget {
+model LivenessDecisionTarget {


This is a retro breaking change. Shouldn't you use @rename versioning decorator?

I thought it's okay since it's mostly only affecting documentation. We are not changing the actual name inside payload.
BTW, this is some feedback from C# SDK review, but I think it worth to change it at REST level for better naming.

@rename should work for intention to change it going forward.

Let's wait for the final design, we may need to rebuild a lot of models after the change.

azure-sdk · 2024-11-18T01:51:09Z

API change check

APIView has identified API level changes in this PR and created following API reviews.

Common

der3318

applying the patch: #31205 for v1.2

specification/ai/Face/examples/v1.2/FaceRecognitionOperations_FindSimilar.json

specification/ai/Face/examples/v1.2/FaceRecognitionOperations_FindSimilarFromFaceList.json

specification/ai/Face/examples/v1.2/FaceRecognitionOperations_FindSimilarFromLargeFaceList.json

...ai/data-plane/Face/stable/v1.2/examples/LivenessSessionOperations_CreateLivenessSession.json

mikekistler

This is very close -- just need to get the form data parameters all listed separately.

mikekistler · 2024-11-26T01:12:50Z

specification/ai/data-plane/Face/stable/v1.2/Face.json

+          {
+            "name": "Parameters",
+            "in": "formData",
+            "description": "The parameters for creating session.",
+            "required": true,
+            "type": "string"
+          },


I think what you want here is the properties of CreateLivenessWithVerifySessionJsonContent all listed as separate formData parameters. I'm not sure what you have to do in TypeSpec to get that to happen but hopefully @allenjzhang can help you get that figured out.

Do you mean expanding each field in CreateLivenessWithVerifySessionJsonContent as a part in MFD?
Something looks like

"parameters": [ { "name": "livenessOperationMode", "in": "formData", "description": "Type of liveness mode the client should follow.", "required": true, "type": "string" }, { "name": "deviceCorrelationIdSetInClient", "in": "formData", "description": "Type of liveness mode the client should follow.", "required": true, "type": "bool" }, ... { "name": "VerifyImage", "in": "formData", "description": "The image stream for verify. Content-Disposition header field for this part must have filename.", "required": true, "type": "file" } ],

This would be different from the current design. We put all fields inside json and serialize them into a string, and put them inside one part in MFD. I think there is no way to describe current design schema completely in swagger 2.0.

That is what I meant, and when you say

We put all fields inside json and serialize them into a string

I think you mean "We require the user to put all the fields into an object and serialize that to JSON". AND the REST API gives no indication of this or what fields belong there. So a user trying to use the REST API would be completely stymied.

Make sense to me.
BTW, should we also change the name "VerifyImage" to camelCase?

@mikekistler Following up on Han's question, should we use camel-case or pascal-case for the parameter names? i.e. verifyImage or VerifyImage? Thanks.

Camel case is probably best, as that is what we recommend for JSON. But we don't have formal guidance on field names in multipart/form-data so I think there is wiggle room here.

mikekistler

Looks good! 👍

Thanks for all the fixes!

Han-msft · 2024-12-24T04:31:52Z

Waiting for service deployment, PR will be merged when all the backend work are ready.

Han-msft · 2025-01-18T00:18:51Z

/azp run

azure-pipelines · 2025-01-18T00:19:09Z

Azure Pipelines successfully started running 3 pipeline(s).

Add face 1.2

1b7c640

Han-msft requested a review from a team as a code owner October 15, 2024 01:52

Han-msft requested review from tg-msft and weidongxu-microsoft and removed request for a team October 15, 2024 01:52

Add example and readme

7f00108

AzureRestAPISpecReview added BreakingChangeReviewRequired <valid label in PR review process>add this label when breaking change review is required data-plane new-api-version TypeSpec Authored with TypeSpec labels Oct 15, 2024

This was referenced Oct 15, 2024

[AutoPR azure-ai-vision-face] Add AI Face next GA version azure-sdk/azure-sdk-for-java#12906

Closed

[AutoPR Azure.AI.Vision.Face] Add AI Face next GA version azure-sdk/azure-sdk-for-net#9487

Closed

azure-sdk added the BreakingChange-Python-Sdk label Oct 15, 2024

azure-sdk mentioned this pull request Oct 15, 2024

[AutoPR azure-ai-vision-face] Add AI Face next GA version azure-sdk/azure-sdk-for-python#9078

Closed

Han-msft added 2 commits October 15, 2024 02:28

Correct version in example

cd104ef

Remove operation result

65531c6

azure-sdk removed the BreakingChange-Python-Sdk label Oct 19, 2024

azure-sdk mentioned this pull request Oct 19, 2024

[Cognitive Services Face API - Azure AI Vision Face API] API Review #31108

Closed

mikekistler added the BreakingChange-Approved-Previously Changes were reviewed and approved in a previous PR label Oct 22, 2024

mikekistler approved these changes Oct 22, 2024

View reviewed changes

weidongxu-microsoft approved these changes Oct 23, 2024

View reviewed changes

weidongxu-microsoft reviewed Oct 23, 2024

View reviewed changes

specification/ai/Face/routes.persondirectory.tsp Show resolved Hide resolved

Han-msft added 2 commits October 31, 2024 03:35

Update model and description

1b9adcc

Update model name

bb228af

allenjzhang reviewed Oct 31, 2024

View reviewed changes

Han-msft and others added 3 commits November 18, 2024 01:23

suppress casing-style

bb284b6

Format tsp

72a9fcc

Merge branch 'main' into hachiang/face-v1.2

90209b3

Align decision casing

5629bb2

der3318 suggested changes Nov 20, 2024

View reviewed changes

Han-msft added 4 commits November 20, 2024 03:58

Use operation state for attempt

f9844a6

Correct find similar example response

3b06114

Remove json request for create liveness with verify seesion

a5441ee

Update example and client.tsp

e90099b

nabilat reviewed Nov 22, 2024

View reviewed changes

...ai/data-plane/Face/stable/v1.2/examples/LivenessSessionOperations_CreateLivenessSession.json Outdated Show resolved Hide resolved

nabilat approved these changes Nov 25, 2024

View reviewed changes

mikekistler requested changes Nov 26, 2024

View reviewed changes

Han-msft added 3 commits November 29, 2024 03:04

Spread liveness parameter into MFD

44d3eca

Update liveness example

38925de

Change document

c814f5e

mikekistler approved these changes Dec 3, 2024

View reviewed changes

mikekistler added the APIStewardshipBoard-SignedOff The Azure API Stewardship team has reviewed and approved the changes. label Dec 3, 2024

microsoft-github-policy-service bot added the no-recent-activity There has been no recent activity on this issue. label Dec 23, 2024

Han-msft removed the no-recent-activity There has been no recent activity on this issue. label Dec 24, 2024

microsoft-github-policy-service bot added the no-recent-activity There has been no recent activity on this issue. label Jan 13, 2025

Han-msft added PublishToCustomers Acknowledgement the changes will be published to Azure customers. and removed no-recent-activity There has been no recent activity on this issue. labels Jan 13, 2025

Han-msft enabled auto-merge (squash) January 18, 2025 00:14

Han-msft removed the request for review from tg-msft January 18, 2025 00:15

Merge branch 'main' into hachiang/face-v1.2

71ccd39

Han-msft merged commit 24d856b into Azure:main Jan 18, 2025
26 of 29 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add AI Face next GA version #31023

Add AI Face next GA version #31023

Han-msft commented Oct 15, 2024 •

edited by azure-sdk

Loading

openapi-pipeline-app bot commented Oct 15, 2024 •

edited

Loading

openapi-pipeline-app bot commented Oct 15, 2024 •

edited

Loading

mikekistler commented Oct 19, 2024

azure-pipelines bot commented Oct 19, 2024

mikekistler commented Oct 22, 2024

mikekistler left a comment

allenjzhang Oct 31, 2024

Han-msft Nov 1, 2024

allenjzhang Nov 5, 2024

Han-msft Nov 5, 2024

azure-sdk commented Nov 18, 2024 •

edited

Loading

der3318 left a comment

mikekistler left a comment

mikekistler Nov 26, 2024

Han-msft Nov 26, 2024

mikekistler Nov 26, 2024

Han-msft Nov 27, 2024

nabilat Nov 27, 2024

mikekistler Nov 27, 2024

Han-msft Nov 29, 2024

mikekistler left a comment

Han-msft commented Dec 24, 2024

Han-msft commented Jan 18, 2025

azure-pipelines bot commented Jan 18, 2025

Add AI Face next GA version #31023

Add AI Face next GA version #31023

Conversation

Han-msft commented Oct 15, 2024 • edited by azure-sdk Loading

Data Plane API Specification Update Pull Request

PR review workflow diagram

API Info: The Basics

Change Scope

Viewing API changes

Suppressing failures

❔Got questions? Need additional info?? We are here to help!

Tooling

Guidelines & Specifications

Helpful Links

Getting help

openapi-pipeline-app bot commented Oct 15, 2024 • edited Loading

Next Steps to Merge

openapi-pipeline-app bot commented Oct 15, 2024 • edited Loading

Generated ApiView

mikekistler commented Oct 19, 2024

azure-pipelines bot commented Oct 19, 2024

mikekistler commented Oct 22, 2024

mikekistler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

azure-sdk commented Nov 18, 2024 • edited Loading

der3318 left a comment

Choose a reason for hiding this comment

mikekistler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikekistler left a comment

Choose a reason for hiding this comment

Han-msft commented Dec 24, 2024

Han-msft commented Jan 18, 2025

azure-pipelines bot commented Jan 18, 2025

Han-msft commented Oct 15, 2024 •

edited by azure-sdk

Loading

openapi-pipeline-app bot commented Oct 15, 2024 •

edited

Loading

openapi-pipeline-app bot commented Oct 15, 2024 •

edited

Loading

azure-sdk commented Nov 18, 2024 •

edited

Loading