De structuur PersonDirectory gebruiken

Voor het uitvoeren van gezichtsherkenningsbewerkingen, zoals Identificeren en Vergelijkbare zoeken, moeten klanten van de Face-API een lijst met verschillende Person-objecten maken. De nieuwe PersonDirectory is een gegevensstructuur die unieke id's, optionele naamreeksen en optionele tekenreeksen voor gebruikersmetagegevens bevat voor elke Person-identiteit die aan de directory is toegevoegd.

Momenteel biedt de Face-API de LargePersonGroup-structuur, die vergelijkbare functionaliteit heeft, maar beperkt is tot 1 miljoen identiteiten. De persondirectory-structuur kan worden opgeschaald tot 75 miljoen identiteiten.

Een ander belangrijk verschil tussen PersonDirectory en eerdere gegevensstructuren is dat u geen Train-aanroepen meer hoeft te doen nadat u gezichten hebt toegevoegd aan een Person-object. Het updateproces vindt automatisch — plaats.

Vereisten

• Azure-abonnement: Maak een gratis abonnement aan.
• Zodra u uw Azure-abonnement hebt, maakt u een Face-resource in de Azure Portal om uw sleutel en eindpunt op te halen. Nadat de app is geïmplementeerd, klikt u op Ga naar resource.
  • U hebt de sleutel en het eindpunt nodig van de resource die u maakt om de toepassing te verbinden met de Face-API. U plakt uw sleutel en eindpunt in de onderstaande code.
  • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen en later upgraden naar een betaalde laag voor productie.

Personen toevoegen aan de PersonDirectory

Personen zijn de basisinschrijvingseenheden in de PersonDirectory. Zodra u een persoon aan de map toevoegt, kunt u per herkenningsmodel maximaal 248 gezichtsafbeeldingen toevoegen aan die persoon. Vervolgens kunt u gezichten op basis van deze gezichten identificeren met behulp van verschillende scopes.

De persoon maken

Als u een persoon wilt maken, moet u de CreatePerson-API aanroepen en een naam of userData-eigenschapswaarde verstrekken.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var addPersonUri = "https:// {endpoint}/face/v1.0-preview/persons";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example Person");
body.Add("userData", "User defined data");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(addPersonUri, content); 
}

De aanroep CreatePerson retourneren een gegenereerde id voor de Persoon en een bewerkingslocatie. De person-gegevens worden asynchroon verwerkt, dus u gebruikt de locatie van de bewerking om de resultaten op te halen.

Wacht tot de asynchrone bewerking is voltooid

U moet de status van de asynsynquerybewerking opvragen met behulp van de geretourneerde bewerkingslocatiereeks om de voortgang te controleren.

Eerst definieert u een gegevensmodel zoals het volgende om het statusreactie te verwerken.

[Serializable]
public class AsyncStatus
{
    [DataMember(Name = "status")]
    public string Status { get; set; }

    [DataMember(Name = "createdTime")]
    public DateTime CreatedTime { get; set; }

    [DataMember(Name = "lastActionTime")]
    public DateTime? LastActionTime { get; set; }

    [DataMember(Name = "finishedTime", EmitDefaultValue = false)]
    public DateTime? FinishedTime { get; set; }

    [DataMember(Name = "resourceLocation", EmitDefaultValue = false)]
    public string ResourceLocation { get; set; }

    [DataMember(Name = "message", EmitDefaultValue = false)]
    public string Message { get; set; }
}

Met behulp van de bovenstaande HttpResponseMessage kunt u vervolgens de URL peilen en wachten op resultaten.

string operationLocation = response.Headers.GetValues("Operation-Location").FirstOrDefault();

Stopwatch s = Stopwatch.StartNew();
string status = "notstarted";
do
{
    if (status == "succeeded")
    {
        await Task.Delay(500);
    }

    var operationResponseMessage = await client.GetAsync(operationLocation);

    var asyncOperationObj = JsonConvert.DeserializeObject<AsyncStatus>(await operationResponseMessage.Content.ReadAsStringAsync());
    status = asyncOperationObj.Status;

} while ((status == "running" || status == "notstarted") && s.Elapsed < TimeSpan.FromSeconds(30));

Zodra de status 'geslaagd' is, wordt het object Person beschouwd als toegevoegd aan de map.

Gezichten toevoegen aan personen

Zodra u de persoons-id van de aanroep Persoon maken hebt, kunt u maximaal 248 gezichtsafbeeldingen toevoegen aan een Persoon per herkenningsmodel. Geef het herkenningsmodel (en eventueel het detectiemodel) op dat in de aanroep moet worden gebruikt, omdat gegevens onder elk herkenningsmodel afzonderlijk worden verwerkt in de PersonDirectory.

De momenteel ondersteunde herkenningsmodellen zijn:

• Recognition_02
• Recognition_03
• Recognition_04

Als de afbeelding meerdere gezichten bevat, moet u bovendien het rechthoekige begrensingsvak opgeven voor het gezicht dat het beoogde doel is. Met de volgende code worden gezichten toegevoegd aan een Person-object.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

// Optional query strings for more fine grained face control
var queryString = "userData={userDefinedData}&targetFace={left,top,width,height}&detectionModel={detectionModel}";
var uri = "https://{endpoint}/face/v1.0-preview/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces?" + queryString;

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("url", "{image url}");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Na de aanroep Gezichten toevoegen worden de gezichtsgegevens asynchroon verwerkt en moet u wachten op het slagen van de bewerking op dezelfde manier als voorheen.

Wanneer de bewerking voor het optellingsgezicht is uitgevoerd, zijn de gegevens gereed voor in Aanroepen identificeren.

Een DynamicPersonGroup maken en bijwerken

DynamicPersonGroups zijn verzamelingen verwijzingen naar Person-objecten binnen een PersonDirectory; ze worden gebruikt om subsets van de map te maken. Een veelvoorkomende toepassing is wanneer u minder fout-positieven en een grotere nauwkeurigheid wilt krijgen in een Identify-bewerking door het bereik te beperken tot alleen de Person-objecten die u verwacht te vinden. Praktische gebruiksvoorbeelden zijn onder andere directories voor specifieke toegang tot het gebouw binnen een grotere campus of organisatie. De organisatiemap kan 5 miljoen personen bevatten, maar u hoeft alleen een specifieke 800 personen te zoeken voor een bepaald gebouw. U maakt dus een DynamicPersonGroup met deze specifieke personen.

Als u al eerder een PersonGroup hebt gebruikt, moet u rekening houden met twee belangrijke verschillen:

• Elke persoon in een DynamicPersonGroup is een verwijzing naar de werkelijke Persoon in de PersonDirectory, wat betekent dat het niet nodig is om een persoon in elke groep opnieuw te maken.
• Zoals vermeld in de vorige secties, is het niet nodig om Train-aanroepen uit te voeren, omdat de gezichtsgegevens automatisch op mapniveau worden verwerkt.

De groep maken

Als u een DynamicPersonGroup wilt maken, moet u een groeps-id met alfanumerieke tekens of streepjes geven. Deze id werkt als de unieke id voor alle gebruiksdoeleinden van de groep.

Er zijn twee manieren om een groepsverzameling te initialiseren. U kunt in eerste instantie een lege groep maken en deze later vullen:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example DynamicPersonGroup");
body.Add("userData", "User defined data");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PutAsync(uri, content);
}

Dit proces is onmiddellijk en u hoeft niet te wachten tot asynchrone bewerkingen zijn geslaagd.

U kunt deze ook maken met een set person-ID's die deze verwijzingen vanaf het begin bevatten door de set op te geven in het argument AddPersonIds:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example DynamicPersonGroup");
body.Add("userData", "User defined data");
body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PutAsync(uri, content);

    // Async operation location to query the completion status from
    var operationLocation = response.Headers.Get("Operation-Location");
}

DynamicPersonGroup bijwerken

Na het maken van de eerste keer kunt u Person-verwijzingen toevoegen aan en verwijderen uit de DynamicPersonGroup met de API Dynamische persoonsgroep bijwerken. Als u Person-objecten wilt toevoegen aan de groep, vermeldt u de persoons-ID's in het argument addPersonsIds. Als u Person-objecten wilt verwijderen, vermeldt u deze in het argument removePersonIds. Zowel toevoegen als verwijderen kan in één aanroep worden uitgevoerd:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example Dynamic Person Group updated");
body.Add("userData", "User defined data updated");
body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("removePersonIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PatchAsync(uri, content);

    // Async operation location to query the completion status from
    var operationLocation = response.Headers.Get("Operation-Location");
}

Zodra de aanroep is retourneert, worden de updates voor de verzameling weergegeven wanneer de groep wordt opgevraagd. Net als bij de API voor het maken, geeft de geretourneerde bewerking de updatestatus aan van de relatie tussen personen en groepen voor elke persoon die betrokken is bij de update. U hoeft niet te wachten tot de bewerking is voltooid voordat u verdere update-aanroepen naar de groep maakt.

Gezichten in een PersonDirectory identificeren

De meest voorkomende manier om gezichtsgegevens in een PersonDirectory te gebruiken, is door de ingeschreven Person-objecten te vergelijken met een bepaald gezicht en de meest waarschijnlijke kandidaat te identificeren waar deze bij hoort. Er kunnen meerdere gezichten worden opgegeven in de aanvraag en elk ervan ontvangt een eigen set vergelijkingsresultaten in het antwoord.

In PersonDirectory zijn er drie typen scopes die elk gezicht kan worden geïdentificeerd op basis van:

Scenario 1: Identificeren op basis van een DynamicPersonGroup

Als u de eigenschap dynamicPersonGroupId opgeeft in de aanvraag, wordt het gezicht vergeleken met elke persoon waarnaar wordt verwezen in de groep. Er kan slechts één DynamicPersonGroup worden geïdentificeerd in een aanroep.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

// Optional query strings for more fine grained face control
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("dynamicPersonGroupId", "{dynamicPersonGroupIdToIdentifyIn}");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Scenario 2: Identificeren op basis van een specifieke lijst met personen

U kunt ook een lijst met persoons-ID's opgeven in de eigenschap personIds om het gezicht te vergelijken met elk ervan.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
            
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("personIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Scenario 3: Identificeren op basis van de volledige PersonDirectory

Door één sterretje op te geven in de eigenschap personIds in de aanvraag, wordt het gezicht vergeleken met elke persoon die is ingeschreven in de PersonDirectory.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
            
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("personIds", new List<string>{"*"});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Voor alle drie de scenario's vergelijkt de identificatie alleen het binnenkomende gezicht met gezichten waarvan de AddPersonFace-aanroep is geretourneerd met een 'geslaagd'-antwoord.

Gezichten controleren op personen in de PersonDirectory

Met een gezichts-id die wordt geretourneerd door een detectie-aanroep, kunt u controleren of het gezicht behoort tot een specifieke persoon die is ingeschreven in de PersonDirectory. Geef de persoon op met behulp van de eigenschap personId.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/verify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceId", "{guid1}");
body.Add("personId", "{guid1}");
var jsSerializer = new JavaScriptSerializer();
byte[] byteData = Encoding.UTF8.GetBytes(jsSerializer.Serialize(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Het antwoord bevat een Booleaanse waarde die aangeeft of de service het nieuwe gezicht beschouwt als behorend bij dezelfde persoon en een betrouwbaarheidsscore voor de voorspelling.

Volgende stappen

In deze handleiding hebt u geleerd hoe u de structuur PersonDirectory gebruikt om gezichts- en persoonsgegevens voor uw Face-app op te slaan. Hierna leert u de best practices voor het toevoegen van gezichtsgegevens van uw gebruikers.

• Best practices voor het toevoegen van gebruikers