clarify sync and async calls and the dependency

Author: der3318

articles/ai-services/computer-vision/how-to/use-persondirectory.md

@@ -238,7 +238,7 @@ using (var content = new ByteArrayContent(byteData))
 ```
 
 > [!NOTE]
-> As soon as the call returns, the created **DynamicPersonGroup** will be ready to use in an Identify call, with any **Person** references provided in the process. The completion status of the returned operation ID, on the other hand, indicates the update status of the person-to-group relationship.
+> As soon as the call returns, the created **DynamicPersonGroup** will be ready to use in an Identify call, with any **Person** references provided in the process. The completion status of the returned operation ID, on the other hand, only indicates the update status for [Get Dynamic Person Group References](/rest/api/face/person-directory-operations/get-dynamic-person-group-references) lookup calls.
 
 ### Update the DynamicPersonGroup
 
@@ -393,6 +393,97 @@ using (var content = new ByteArrayContent(byteData))
 
 The response will contain a Boolean value indicating whether the service considers the new face to belong to the same **Person**, and a confidence score for the prediction.
 
+## Overview of asynchronous operations
+
+The tables below summarize whether a **PersonDirectory** management call is a long-running operation (LRO) processed asynchronously, or it completes immediately and synchronously:
+
+| Person/Face Management | URI | LRO? |
+| --- | --- | --- |
+| [Get Persons](/rest/api/face/person-directory-operations/get-persons) | /persons | |
+| [Create Person](/rest/api/face/person-directory-operations/create-person) | /persons | 🔴 |
+| [Get Person](/rest/api/face/person-directory-operations/get-person) | /persons/{personId} | |
+| [Update Person](/rest/api/face/person-directory-operations/update-person) | /persons/{personId} | |
+| [Delete Person](/rest/api/face/person-directory-operations/delete-person) | /persons/{personId} | 🔴 |
+| [Get Person Faces](/rest/api/face/person-directory-operations/get-person-faces) | /persons/{personId}/recognitionModels/{model}/persistedfaces | |
+| [Add Person Face](/rest/api/face/person-directory-operations/add-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces | 🔴 |
+| [Add Person Face From Url](/rest/api/face/person-directory-operations/add-person-face-from-url) | /persons/{personId}/recognitionModels/{model}/persistedfaces | 🔴 |
+| [Get Person Face](/rest/api/face/person-directory-operations/get-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | |
+| [Update Person Face](/rest/api/face/person-directory-operations/update-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | |
+| [Delete Person Face](/rest/api/face/person-directory-operations/delete-person-face) | /persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId} | 🔴 |
+
+| Group Management | URI | LRO? |
+| --- | --- | --- |
+| [Get Dynamic Person Groups](/rest/api/face/person-directory-operations/get-dynamic-person-groups) | /dynamicpersongroups | |
+| [Create Dynamic Person Group](/rest/api/face/person-directory-operations/create-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId}	| |
+| [Create Dynamic Person Group With Person](/rest/api/face/person-directory-operations/create-dynamic-person-group-with-person) | /dynamicpersongroups/{dynamicPersonGroupId}	| 🔴 |
+| [Get Dynamic Person Group](/rest/api/face/person-directory-operations/get-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | |
+| [Update Dynamic Person Group](/rest/api/face/person-directory-operations/update-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | |
+| [Update Dynamic Person Group With Person Changes](/rest/api/face/person-directory-operations/update-dynamic-person-group-with-person-changes) | /dynamicpersongroups/{dynamicPersonGroupId} | 🔴 |
+| [Delete Dynamic Person Group](/rest/api/face/person-directory-operations/delete-dynamic-person-group) | /dynamicpersongroups/{dynamicPersonGroupId} | 🔴 |
+| [Get Dynamic Person Group Persons](/rest/api/face/person-directory-operations/get-dynamic-person-group-persons) | /dynamicpersongroups/{dynamicPersonGroupId}/persons | |
+| [Get Dynamic Person Group References](/rest/api/face/person-directory-operations/get-dynamic-person-group-references) | /persons/{personId}/dynamicPersonGroupReferences | |
+
+The following code illustrates the dependencies of these asynchronous operations:
+
+```csharp
+var createPersonResponse = await CreatePersonAsync();
+var personId = createPersonResponse.PersonId;
+
+// faces can be added once the person creation HTTP call returns, even if it's still processing
+var addPersonFaceResponse = await AddPersonFaceAsync(personId);
+var addPersonFaceFromUrlResponse = await AddPersonFaceFromUrlAsync(personId);
+
+switch (scenario)
+{
+    case Scenario.Verify:
+        // only need to ensure the addition of face data has propagated
+        await WaitForLongRunningOperationsAsync(new[]
+        {
+            addPersonFaceResponse.OperationLocation,
+            addPersonFaceFromUrlResponse.OperationLocation
+        });
+        await VerifyFromPersonDirectoryAsync(queryFaceId, personId);
+        break;
+
+    case Scenario.IdentifyInPersonDirectory:
+        // ensure person creation and face data enrollment finish successfully
+        await WaitForLongRunningOperationsAsync(new[]
+        {
+            createPersonResponse.OperationLocation,
+            addPersonFaceResponse.OperationLocation,
+            addPersonFaceFromUrlResponse.OperationLocation
+        });
+        await IdentifyFromPersonDirectoryAsync(queryFaceId);
+        break;
+
+    case Scenario.IdentifyAgainstDynamicPersonGroup:
+        // person creation needs to be completed before it can be added to a group
+        await WaitForLongRunningOperationsAsync(new[]
+        {
+            createPersonResponse.OperationLocation
+        });
+        var groupResponse = await CreateOrUpdateDynamicPersonGroupWithPersonChangesAsync(groupId, [personId]);
+        // and make sure face data are ready before identification
+        await WaitForLongRunningOperationsAsync(new[]
+        {
+            addPersonFaceResponse.OperationLocation,
+            addPersonFaceFromUrlResponse.OperationLocation
+        });
+        await IdentifyFromDynamicPersonGroupAsync(queryFaceId, groupId);
+        // optionally check the person-to-group relationship, which requires the completion of the group's creation or updating call
+        await WaitForLongRunningOperationsAsync(new[]
+        {
+            groupResponse.OperationLocation
+        });
+        var groupIds = await GetDynamicPersonGroupReferencesAsync(personId);
+        break;
+
+    default:
+        break;
+}
+```
+
+
 ## Next steps
 
 In this guide, you learned how to use the **PersonDirectory** structure to store face and person data for your Face app. Next, learn the best practices for adding your users' face data.