Quickstart: Use a biblioteca do cliente FaceQuickstart: Use the Face client library

Começa com a biblioteca de clientes Face para .NET.Get started with the Face client library for .NET. Siga estes passos para instalar a embalagem e experimente o código de exemplo para tarefas básicas.Follow these steps to install the package and try out the example code for basic tasks. O serviço Face fornece-lhe acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Utilize a biblioteca cliente Face para .NET para:Use the Face client library for .NET to:

Documentação de referência | Código fonte da biblioteca | Pacote (NuGet) | AmostrasReference documentation | Library source code | Package (NuGet) | Samples

Pré-requisitosPrerequisites

  • A versão atual de .NET Core.The current version of .NET Core.
  • Subscrição Azure - Crie uma gratuitamenteAzure subscription - Create one for free
  • Assim que tiver a subscrição do Azure, Azure para obter a sua chave e ponto final.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. Depois de implementar, clique em Ir para o recurso.After it deploys, click Go to resource.
    • Necessitará da chave e ponto final do recurso que criar para ligar a sua aplicação à API face.You will need the key and endpoint from the resource you create to connect your application to the Face API. Colará a chave e o ponto final no código abaixo mais tarde no arranque rápido.You'll paste your key and endpoint into the code below later in the quickstart.
    • Pode utilizar o nível de preços gratuitos F0 para experimentar o serviço e fazer upgrade mais tarde para um nível pago para produção.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Depois de obter uma chave e ponto final, crie variáveis ambientais para o URL chave e ponto final, nomeado FACE_SUBSCRIPTION_KEY FACE_ENDPOINT e, respectivamente.After you get a key and endpoint, create environment variables for the key and endpoint URL, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT, respectively.

ConfiguraçãoSetting up

Criar uma nova aplicação C#Create a new C# application

Crie uma nova aplicação .NET Core no seu editor preferido ou IDE.Create a new .NET Core application in your preferred editor or IDE.

Numa janela de consola (como cmd, PowerShell ou Bash), utilize o dotnet new comando para criar uma nova aplicação de consola com o nome face-quickstart .In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name face-quickstart. Este comando cria um projeto simples "Hello World" C# com um único ficheiro de origem: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

dotnet new console -n face-quickstart

Mude o seu diretório para a pasta de aplicações recém-criada.Change your directory to the newly created app folder. Pode construir a aplicação com:You can build the application with:

dotnet build

A saída de construção não deve conter avisos ou erros.The build output should contain no warnings or errors.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

A partir do diretório do projeto, abra o ficheiro Program.cs no seu editor preferido ou IDE.From the project directory, open the Program.cs file in your preferred editor or IDE. Adicione as using seguintes diretivas:Add the following using directives:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;

using Microsoft.Azure.CognitiveServices.Vision.Face;
using Microsoft.Azure.CognitiveServices.Vision.Face.Models;

No método da Main aplicação, crie variáveis para o ponto final e chave Azure do seu recurso.In the application's Main method, create variables for your resource's Azure endpoint and key.

// From your Face subscription in the Azure portal, get your subscription key and endpoint.
// Set your environment variables using the names below. Close and reopen your project for changes to take effect.
string SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("FACE_SUBSCRIPTION_KEY");
string ENDPOINT = Environment.GetEnvironmentVariable("FACE_ENDPOINT");

Instalar a biblioteca do clienteInstall the client library

Dentro do diretório de aplicações, instale a biblioteca cliente Face para .NET com o seguinte comando:Within the application directory, install the Face client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Vision.Face --version 2.5.0-preview.1

Se estiver a utilizar o Visual Studio IDE, a biblioteca do cliente está disponível como um pacote NuGet transferível.If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

Modelo de objetoObject model

As seguintes classes e interfaces lidam com algumas das principais características da biblioteca cliente Face .NET:The following classes and interfaces handle some of the major features of the Face .NET client library:

NameName DescriptionDescription
FaceClientFaceClient Esta classe representa a sua autorização para usar o serviço Face, e precisa dele para toda a funcionalidade Face.This class represents your authorization to use the Face service, and you need it for all Face functionality. Você instantanea-o com as suas informações de subscrição, e você usá-lo para produzir instâncias de outras classes.You instantiate it with your subscription information, and you use it to produce instances of other classes.
Operações faciaisFaceOperations Esta classe lida com as tarefas básicas de deteção e reconhecimento que pode fazer com rostos humanos.This class handles the basic detection and recognition tasks that you can do with human faces.
Face detetadoDetectedFace Esta classe representa todos os dados que foram detetados a partir de um único rosto numa imagem.This class represents all of the data that was detected from a single face in an image. Pode usá-lo para obter informações detalhadas sobre o rosto.You can use it to retrieve detailed information about the face.
Operações FaceListFaceListOperations Esta classe gere as construções FaceList armazenadas em nuvem, que armazenam um conjunto variado de rostos.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonExtensionsPersonGroupPersonExtensions Esta classe gere as construções de Pessoas armazenadas em nuvem, que armazenam um conjunto de rostos que pertencem a uma única pessoa.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupOperaçõesPersonGroupOperations Esta classe gere as construções do PersonGroup armazenadas na nuvem, que armazenam um conjunto de objetos pessoais variados.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
Operações ShapshotShapshotOperations Esta classe gere a funcionalidade Snapshot.This class manages the Snapshot functionality. Pode usá-lo para guardar temporariamente todos os seus dados face baseados na nuvem e migrar esses dados para uma nova subscrição do Azure.You can use it to temporarily save all of your cloud-based Face data and migrate that data to a new Azure subscription.

Exemplos de códigoCode examples

Os snippets de código abaixo mostram-lhe como fazer as seguintes tarefas com a biblioteca cliente Face para .NET:The code snippets below show you how to do the following tasks with the Face client library for .NET:

Autenticar o clienteAuthenticate the client

Nota

Este quickstart assume que criou variáveis ambientais para a sua chave face e ponto final, nomeado FACE_SUBSCRIPTION_KEY e FACE_ENDPOINT .This quickstart assumes you've created environment variables for your Face key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT.

Num novo método, instantaneamente um cliente com o seu ponto final e chave.In a new method, instantiate a client with your endpoint and key. Crie um objeto ApiKeyServiceClientCredentials com a sua chave e use-o com o seu ponto final para criar um objeto FaceClient.Create a ApiKeyServiceClientCredentials object with your key, and use it with your endpoint to create a FaceClient object.

/*
 *	AUTHENTICATE
 *	Uses subscription key and region to create a client.
 */
public static IFaceClient Authenticate(string endpoint, string key)
{
    return new FaceClient(new ApiKeyServiceClientCredentials(key)) { Endpoint = endpoint };
}

Provavelmente vai querer chamar este método no Main método.You'll likely want to call this method in the Main method.

// Authenticate.
IFaceClient client = Authenticate(ENDPOINT, SUBSCRIPTION_KEY);

Declarar campos de ajudaDeclare helper fields

São necessários os seguintes campos para várias das operações face que irá adicionar mais tarde.The following fields are needed for several of the Face operations you'll add later. Na raiz da sua classe, defina a seguinte cadeia de URL.At the root of your class, define the following URL string. Este URL aponta para uma pasta de imagens de amostra.This URL points to a folder of sample images.

// Used for all examples.
// URL for the images.
const string IMAGE_BASE_URL = "https://csdx.blob.core.windows.net/resources/Face/Images/";

Defina as cordas para apontar para os diferentes tipos de modelos de reconhecimento.Define strings to point to the different recognition model types. Mais tarde, poderá especificar qual o modelo de reconhecimento que pretende utilizar para deteção facial.Later on, you'll be able to specify which recognition model you want to use for face detection. Consulte Especificar um modelo de reconhecimento para obter informações sobre estas opções.See Specify a recognition model for information on these options.

// Used in the Detect Faces and Verify examples.
// Recognition model 2 is used for feature extraction, use 1 to simply recognize/detect a face. 
// However, the API calls to Detection that are used with Verify, Find Similar, or Identify must share the same recognition model.
const string RECOGNITION_MODEL2 = RecognitionModel.Recognition02;
const string RECOGNITION_MODEL1 = RecognitionModel.Recognition01;

Detetar rostos numa imagemDetect faces in an image

Adicione a chamada de método a seguir ao seu método principal.Add the following method call to your main method. Vai definir o método a seguir.You'll define the method next. A operação de Deteção final levará um objeto FaceClient, um URL de imagem e um modelo de reconhecimento.The final Detect operation will take a FaceClient object, an image URL, and a recognition model.

// Detect - get features from faces.
DetectFaceExtract(client, IMAGE_BASE_URL, RECOGNITION_MODEL2).Wait();

Obtenha objetos faciais detetadosGet detected face objects

No bloco de código seguinte, o DetectFaceExtract método deteta rostos em três das imagens no URL dado e cria uma lista de objetos DetectedFace na memória do programa.In the next block of code, the DetectFaceExtract method detects faces in three of the images at the given URL and creates a list of DetectedFace objects in program memory. A lista de valores FaceAttributeType especifica quais as características a extrair.The list of FaceAttributeType values specifies which features to extract.

/* 
 * DETECT FACES
 * Detects features from faces and IDs them.
 */
public static async Task DetectFaceExtract(IFaceClient client, string url, string recognitionModel)
{
    Console.WriteLine("========DETECT FACES========");
    Console.WriteLine();

    // Create a list of images
    List<string> imageFileNames = new List<string>
                    {
                        "detection1.jpg",    // single female with glasses
                        // "detection2.jpg", // (optional: single man)
                        // "detection3.jpg", // (optional: single male construction worker)
                        // "detection4.jpg", // (optional: 3 people at cafe, 1 is blurred)
                        "detection5.jpg",    // family, woman child man
                        "detection6.jpg"     // elderly couple, male female
                    };

    foreach (var imageFileName in imageFileNames)
    {
        IList<DetectedFace> detectedFaces;

        // Detect faces with all attributes from image url.
        detectedFaces = await client.Face.DetectWithUrlAsync($"{url}{imageFileName}",
                returnFaceAttributes: new List<FaceAttributeType> { FaceAttributeType.Accessories, FaceAttributeType.Age,
                FaceAttributeType.Blur, FaceAttributeType.Emotion, FaceAttributeType.Exposure, FaceAttributeType.FacialHair,
                FaceAttributeType.Gender, FaceAttributeType.Glasses, FaceAttributeType.Hair, FaceAttributeType.HeadPose,
                FaceAttributeType.Makeup, FaceAttributeType.Noise, FaceAttributeType.Occlusion, FaceAttributeType.Smile },
                recognitionModel: recognitionModel);

        Console.WriteLine($"{detectedFaces.Count} face(s) detected from image `{imageFileName}`.");

Mostrar dados faciais detetadosDisplay detected face data

O resto do DetectFaceExtract método analisa e imprime os dados de atributos para cada face detetada.The rest of the DetectFaceExtract method parses and prints the attribute data for each detected face. Cada atributo deve ser especificado separadamente na chamada API de deteção facial original (na lista FaceAttributeType).Each attribute must be specified separately in the original face detection API call (in the FaceAttributeType list). O código seguinte processa cada atributo, mas provavelmente só terá de usar um ou poucos.The following code processes every attribute, but you will likely only need to use one or a few.

        // Parse and print all attributes of each detected face.
        foreach (var face in detectedFaces)
        {
            Console.WriteLine($"Face attributes for {imageFileName}:");

            // Get bounding box of the faces
            Console.WriteLine($"Rectangle(Left/Top/Width/Height) : {face.FaceRectangle.Left} {face.FaceRectangle.Top} {face.FaceRectangle.Width} {face.FaceRectangle.Height}");

            // Get accessories of the faces
            List<Accessory> accessoriesList = (List<Accessory>)face.FaceAttributes.Accessories;
            int count = face.FaceAttributes.Accessories.Count;
            string accessory; string[] accessoryArray = new string[count];
            if (count == 0) { accessory = "NoAccessories"; }
            else
            {
                for (int i = 0; i < count; ++i) { accessoryArray[i] = accessoriesList[i].Type.ToString(); }
                accessory = string.Join(",", accessoryArray);
            }
            Console.WriteLine($"Accessories : {accessory}");

            // Get face other attributes
            Console.WriteLine($"Age : {face.FaceAttributes.Age}");
            Console.WriteLine($"Blur : {face.FaceAttributes.Blur.BlurLevel}");

            // Get emotion on the face
            string emotionType = string.Empty;
            double emotionValue = 0.0;
            Emotion emotion = face.FaceAttributes.Emotion;
            if (emotion.Anger > emotionValue) { emotionValue = emotion.Anger; emotionType = "Anger"; }
            if (emotion.Contempt > emotionValue) { emotionValue = emotion.Contempt; emotionType = "Contempt"; }
            if (emotion.Disgust > emotionValue) { emotionValue = emotion.Disgust; emotionType = "Disgust"; }
            if (emotion.Fear > emotionValue) { emotionValue = emotion.Fear; emotionType = "Fear"; }
            if (emotion.Happiness > emotionValue) { emotionValue = emotion.Happiness; emotionType = "Happiness"; }
            if (emotion.Neutral > emotionValue) { emotionValue = emotion.Neutral; emotionType = "Neutral"; }
            if (emotion.Sadness > emotionValue) { emotionValue = emotion.Sadness; emotionType = "Sadness"; }
            if (emotion.Surprise > emotionValue) { emotionType = "Surprise"; }
            Console.WriteLine($"Emotion : {emotionType}");

            // Get more face attributes
            Console.WriteLine($"Exposure : {face.FaceAttributes.Exposure.ExposureLevel}");
            Console.WriteLine($"FacialHair : {string.Format("{0}", face.FaceAttributes.FacialHair.Moustache + face.FaceAttributes.FacialHair.Beard + face.FaceAttributes.FacialHair.Sideburns > 0 ? "Yes" : "No")}");
            Console.WriteLine($"Gender : {face.FaceAttributes.Gender}");
            Console.WriteLine($"Glasses : {face.FaceAttributes.Glasses}");

            // Get hair color
            Hair hair = face.FaceAttributes.Hair;
            string color = null;
            if (hair.HairColor.Count == 0) { if (hair.Invisible) { color = "Invisible"; } else { color = "Bald"; } }
            HairColorType returnColor = HairColorType.Unknown;
            double maxConfidence = 0.0f;
            foreach (HairColor hairColor in hair.HairColor)
            {
                if (hairColor.Confidence <= maxConfidence) { continue; }
                maxConfidence = hairColor.Confidence; returnColor = hairColor.Color; color = returnColor.ToString();
            }
            Console.WriteLine($"Hair : {color}");

            // Get more attributes
            Console.WriteLine($"HeadPose : {string.Format("Pitch: {0}, Roll: {1}, Yaw: {2}", Math.Round(face.FaceAttributes.HeadPose.Pitch, 2), Math.Round(face.FaceAttributes.HeadPose.Roll, 2), Math.Round(face.FaceAttributes.HeadPose.Yaw, 2))}");
            Console.WriteLine($"Makeup : {string.Format("{0}", (face.FaceAttributes.Makeup.EyeMakeup || face.FaceAttributes.Makeup.LipMakeup) ? "Yes" : "No")}");
            Console.WriteLine($"Noise : {face.FaceAttributes.Noise.NoiseLevel}");
            Console.WriteLine($"Occlusion : {string.Format("EyeOccluded: {0}", face.FaceAttributes.Occlusion.EyeOccluded ? "Yes" : "No")} " +
                $" {string.Format("ForeheadOccluded: {0}", face.FaceAttributes.Occlusion.ForeheadOccluded ? "Yes" : "No")}   {string.Format("MouthOccluded: {0}", face.FaceAttributes.Occlusion.MouthOccluded ? "Yes" : "No")}");
            Console.WriteLine($"Smile : {face.FaceAttributes.Smile}");
            Console.WriteLine();
        }
    }
}

Encontrar rostos semelhantesFind similar faces

O código seguinte requer um único rosto detetado (fonte) e procura um conjunto de outras faces (alvo) para encontrar fósforos.The following code takes a single detected face (source) and searches a set of other faces (target) to find matches. Quando encontra uma correspondência, imprime o ID da face compatível com a consola.When it finds a match, it prints the ID of the matched face to the console.

Detetar rostos para comparaçãoDetect faces for comparison

Primeiro, defina um segundo método de deteção facial.First, define a second face detection method. É necessário detetar rostos em imagens antes de os comparar, e este método de deteção está otimizado para operações de comparação.You need to detect faces in images before you can compare them, and this detection method is optimized for comparison operations. Não extrai atributos faciais detalhados como na secção acima, e usa um modelo de reconhecimento diferente.It doesn't extract detailed face attributes like in the section above, and it uses a different recognition model.

private static async Task<List<DetectedFace>> DetectFaceRecognize(IFaceClient faceClient, string url, string RECOGNITION_MODEL1)
{
    // Detect faces from image URL. Since only recognizing, use the recognition model 1.
    IList<DetectedFace> detectedFaces = await faceClient.Face.DetectWithUrlAsync(url, recognitionModel: RECOGNITION_MODEL1);
    Console.WriteLine($"{detectedFaces.Count} face(s) detected from image `{Path.GetFileName(url)}`");
    return detectedFaces.ToList();
}

Encontrar fósforosFind matches

O método a seguir deteta rostos num conjunto de imagens-alvo e numa única imagem de origem.The following method detects faces in a set of target images and in a single source image. Depois, compara-as e encontra todas as imagens-alvo que são semelhantes à imagem de origem.Then, it compares them and finds all the target images that are similar to the source image.

/*
 * FIND SIMILAR
 * This example will take an image and find a similar one to it in another image.
 */
public static async Task FindSimilar(IFaceClient client, string url, string RECOGNITION_MODEL1)
{
    Console.WriteLine("========FIND SIMILAR========");
    Console.WriteLine();

    List<string> targetImageFileNames = new List<string>
                        {
                            "Family1-Dad1.jpg",
                            "Family1-Daughter1.jpg",
                            "Family1-Mom1.jpg",
                            "Family1-Son1.jpg",
                            "Family2-Lady1.jpg",
                            "Family2-Man1.jpg",
                            "Family3-Lady1.jpg",
                            "Family3-Man1.jpg"
                        };

    string sourceImageFileName = "findsimilar.jpg";
    IList<Guid?> targetFaceIds = new List<Guid?>();
    foreach (var targetImageFileName in targetImageFileNames)
    {
        // Detect faces from target image url.
        var faces = await DetectFaceRecognize(client, $"{url}{targetImageFileName}", RECOGNITION_MODEL1);
        // Add detected faceId to list of GUIDs.
        targetFaceIds.Add(faces[0].FaceId.Value);
    }

    // Detect faces from source image url.
    IList<DetectedFace> detectedFaces = await DetectFaceRecognize(client, $"{url}{sourceImageFileName}", RECOGNITION_MODEL1);
    Console.WriteLine();

    // Find a similar face(s) in the list of IDs. Comapring only the first in list for testing purposes.
    IList<SimilarFace> similarResults = await client.Face.FindSimilarAsync(detectedFaces[0].FaceId.Value, null, null, targetFaceIds);

O seguinte código imprime os detalhes da correspondência para a consola:The following code prints the match details to the console:

foreach (var similarResult in similarResults)
{
    Console.WriteLine($"Faces from {sourceImageFileName} & ID:{similarResult.FaceId} are similar with confidence: {similarResult.Confidence}.");
}
Console.WriteLine();

Identificar um rostoIdentify a face

A operação Identificar tira uma imagem de uma pessoa (ou de várias pessoas) e procura encontrar a identidade de cada rosto na imagem.The Identify operation takes an image of a person (or multiple people) and looks to find the identity of each face in the image. Compara cada rosto detetado a um PersonGroup, uma base de dados de diferentes objetos pessoais cujas características faciais são conhecidas.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known. Para fazer a operação Identificar, primeiro precisa criar e formar um PersonGroupIn order to do the Identify operation, you first need to create and train a PersonGroup

Criar e treinar um grupo de pessoasCreate and train a person group

O código a seguir cria um PersonGroup com seis objetos Pessoais diferentes.The following code creates a PersonGroup with six different Person objects. Associa cada Pessoa a um conjunto de imagens de exemplo, e depois treina para reconhecer cada pessoa pelas suas características faciais.It associates each Person with a set of example images, and then it trains to recognize each person by their facial characteristics. Os objetos pessoais e pessoas do Grupo são utilizados nas operações de Verificação, Identificação e Grupo.Person and PersonGroup objects are used in the Verify, Identify, and Group operations.

Criar Grupo de PessoasCreate PersonGroup

Declare uma variável de corda na raiz da sua classe para representar o ID do PersonGroup que irá criar.Declare a string variable at the root of your class to represent the ID of the PersonGroup you'll create.

static string sourcePersonGroup = null;

Num novo método, adicione o seguinte código.In a new method, add the following code. Este método realizará a operação Identificar.This method will carry out the Identify operation. O primeiro bloco de código associa os nomes das pessoas às suas imagens de exemplo.The first block of code associates the names of persons with their example images.

// Create a dictionary for all your images, grouping similar ones under the same key.
Dictionary<string, string[]> personDictionary =
    new Dictionary<string, string[]>
        { { "Family1-Dad", new[] { "Family1-Dad1.jpg", "Family1-Dad2.jpg" } },
          { "Family1-Mom", new[] { "Family1-Mom1.jpg", "Family1-Mom2.jpg" } },
          { "Family1-Son", new[] { "Family1-Son1.jpg", "Family1-Son2.jpg" } },
          { "Family1-Daughter", new[] { "Family1-Daughter1.jpg", "Family1-Daughter2.jpg" } },
          { "Family2-Lady", new[] { "Family2-Lady1.jpg", "Family2-Lady2.jpg" } },
          { "Family2-Man", new[] { "Family2-Man1.jpg", "Family2-Man2.jpg" } }
        };
// A group photo that includes some of the persons you seek to identify from your dictionary.
string sourceImageFileName = "identification1.jpg";

Em seguida, adicione o seguinte código para criar um objeto Pessoa para cada pessoa no Dicionário e adicione os dados faciais das imagens apropriadas.Next, add the following code to create a Person object for each person in the Dictionary and add the face data from the appropriate images. Cada objeto pessoa está associado com o mesmo PersonGroup através da sua cadeia de ID única.Each Person object is associated with the same PersonGroup through its unique ID string. Lembre-se de passar as client variáveis, e para este url RECOGNITION_MODEL1 método.Remember to pass the variables client, url, and RECOGNITION_MODEL1 into this method.

// Create a person group. 
string personGroupId = Guid.NewGuid().ToString();
sourcePersonGroup = personGroupId; // This is solely for the snapshot operations example
Console.WriteLine($"Create a person group ({personGroupId}).");
await client.PersonGroup.CreateAsync(personGroupId, personGroupId, recognitionModel: recognitionModel);
// The similar faces will be grouped into a single person group person.
foreach (var groupedFace in personDictionary.Keys)
{
    // Limit TPS
    await Task.Delay(250);
    Person person = await client.PersonGroupPerson.CreateAsync(personGroupId: personGroupId, name: groupedFace);
    Console.WriteLine($"Create a person group person '{groupedFace}'.");

    // Add face to the person group person.
    foreach (var similarImage in personDictionary[groupedFace])
    {
        Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
        PersistedFace face = await client.PersonGroupPerson.AddFaceFromUrlAsync(personGroupId, person.PersonId,
            $"{url}{similarImage}", similarImage);
    }
}

Grupo de Pessoas do ComboioTrain PersonGroup

Uma vez extraídos dados faciais das suas imagens e classificado-os em diferentes objetos pessoais, deve treinar o PersonGroup para identificar as características visuais associadas a cada um dos seus objetos Pessoais.Once you've extracted face data from your images and sorted it into different Person objects, you must train the PersonGroup to identify the visual features associated with each of its Person objects. O código a seguir chama o método do comboio assíncronos e sonda os resultados, imprimindo o estado à consola.The following code calls the asynchronous train method and polls the results, printing the status to the console.

// Start to train the person group.
Console.WriteLine();
Console.WriteLine($"Train person group {personGroupId}.");
await client.PersonGroup.TrainAsync(personGroupId);

// Wait until the training is completed.
while (true)
{
    await Task.Delay(1000);
    var trainingStatus = await client.PersonGroup.GetTrainingStatusAsync(personGroupId);
    Console.WriteLine($"Training status: {trainingStatus.Status}.");
    if (trainingStatus.Status == TrainingStatusType.Succeeded) { break; }
}

Este grupo Pessoa e os seus objetos Pessoas associados estão agora prontos para serem utilizados nas operações de Verificação, Identificação ou Grupo.This Person group and its associated Person objects are now ready to be used in the Verify, Identify, or Group operations.

Obtenha uma imagem de testeGet a test image

Note que o código para criar e treinar um grupo de pessoas define uma variável sourceImageFileName .Notice that the code for Create and train a person group defines a variable sourceImageFileName. Esta variável corresponde à imagem de origem — da imagem que contém pessoas para identificar.This variable corresponds to the source image—the image that contains people to identify.

Identificar rostosIdentify faces

O código seguinte pega na imagem de origem e cria uma lista de todos os rostos detetados na imagem.The following code takes the source image and creates a list of all the faces detected in the image. Estes são os rostos que serão identificados contra o Grupo de Pessoas.These are the faces that will be identified against the PersonGroup.

List<Guid> sourceFaceIds = new List<Guid>();
// Detect faces from source image url.
List<DetectedFace> detectedFaces = await DetectFaceRecognize(client, $"{url}{sourceImageFileName}", recognitionModel: recognitionModel);

// Add detected faceId to sourceFaceIds.
foreach (var detectedFace in detectedFaces) { sourceFaceIds.Add(detectedFace.FaceId.Value); }

O próximo código chama a operação IdentifyAsync e imprime os resultados para a consola.The next code snippet calls the IdentifyAsync operation and prints the results to the console. Aqui, o serviço tenta combinar cada face da imagem de origem com uma Pessoa no Grupo de Pessoas.Here, the service attempts to match each face from the source image to a Person in the given PersonGroup. Isto encerra o seu método de identificação.This closes out your Identify method.

// Identify the faces in a person group. 
var identifyResults = await client.Face.IdentifyAsync(sourceFaceIds, personGroupId);

foreach (var identifyResult in identifyResults)
{
    Person person = await client.PersonGroupPerson.GetAsync(personGroupId, identifyResult.Candidates[0].PersonId);
    Console.WriteLine($"Person '{person.Name}' is identified for face in: {sourceImageFileName} - {identifyResult.FaceId}," +
        $" confidence: {identifyResult.Candidates[0].Confidence}.");
}
Console.WriteLine();

Tire uma foto para a migração de dadosTake a snapshot for data migration

A funcionalidade Snapshots permite-lhe mover os dados do Face guardados, como um PersonGrouptreinado, para uma subscrição diferente do Azure Cognitive Services Face.The Snapshots feature lets you move your saved Face data, such as a trained PersonGroup, to a different Azure Cognitive Services Face subscription. Pode querer utilizar esta funcionalidade se, por exemplo, criou um objeto Do PersonGroup usando uma subscrição gratuita e quiser emigrá-la para uma subscrição paga.You may want to use this feature if, for example, you've created a PersonGroup object using a free subscription and want to migrate it to a paid subscription. Consulte os dados do seu rosto para obter uma visão geral da funcionalidade Snapshots.See Migrate your face data for an overview of the Snapshots feature.

Neste exemplo, migrará o PersonGroup que criou na Create e treinará um grupo de pessoas.In this example, you will migrate the PersonGroup you created in Create and train a person group. Pode completar essa secção primeiro, ou criar os seus próprios dados face para migrar.You can either complete that section first, or create your own Face data construct(s) to migrate.

Configurar a subscrição-alvoSet up target subscription

Em primeiro lugar, deve ter uma segunda subscrição do Azure com recurso Face; pode fazê-lo seguindo os passos na secção Configuração.First, you must have a second Azure subscription with a Face resource; you can do this by following the steps in the Setting up section.

Em seguida, defina as seguintes variáveis no Main método do seu programa.Then, define the following variables in the Main method of your program. Terá de criar novas variáveis ambientais para o ID de subscrição da sua conta Azure, bem como a chave, ponto final e ID de subscrição da sua nova conta (alvo).You'll need to create new environment variables for the subscription ID of your Azure account, as well as the key, endpoint, and subscription ID of your new (target) account.

// The Snapshot example needs its own 2nd client, since it uses two different regions.
string TARGET_SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("FACE_SUBSCRIPTION_KEY2");
string TARGET_ENDPOINT = Environment.GetEnvironmentVariable("FACE_ENDPOINT2");
// Grab your subscription ID, from any resource in Azure, from the Overview page (all resources have the same subscription ID). 
Guid AZURE_SUBSCRIPTION_ID = new Guid(Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"));
// Target subscription ID. It will be the same as the source ID if created Face resources from the same
// subscription (but moving from region to region). If they are different subscriptions, add the other
// target ID here.
Guid TARGET_AZURE_SUBSCRIPTION_ID = new Guid(Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"));

Para este exemplo, declare uma variável para o ID do Target PersonGroup — o objeto que pertence à nova subscrição, à qual irá copiar os seus dados.For this example, declare a variable for the ID of the target PersonGroup—the object that belongs to the new subscription, which you will copy your data to.

// The Snapshot example needs its own 2nd client, since it uses two different regions.
string TARGET_SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("FACE_SUBSCRIPTION_KEY2");
string TARGET_ENDPOINT = Environment.GetEnvironmentVariable("FACE_ENDPOINT2");
// Grab your subscription ID, from any resource in Azure, from the Overview page (all resources have the same subscription ID). 
Guid AZURE_SUBSCRIPTION_ID = new Guid(Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"));
// Target subscription ID. It will be the same as the source ID if created Face resources from the same
// subscription (but moving from region to region). If they are different subscriptions, add the other
// target ID here.
Guid TARGET_AZURE_SUBSCRIPTION_ID = new Guid(Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"));

Autenticar cliente alvoAuthenticate target client

Em seguida, adicione o código para autenticar a sua subscrição secundária face.Next, add the code to authenticate your secondary Face subscription.

// Authenticate for another region or subscription (used in Snapshot only).
IFaceClient clientTarget = Authenticate(TARGET_ENDPOINT, TARGET_SUBSCRIPTION_KEY);

Use um instantâneoUse a snapshot

O resto das operações instantâneas devem ser efetuadas num método assíncronos.The rest of the snapshot operations must take place within an asynchronous method.

  1. O primeiro passo é tirar o instantâneo, que guarda os dados faciais da sua subscrição original para uma localização temporária na nuvem.The first step is to take the snapshot, which saves your original subscription's face data to a temporary cloud location. Este método devolve um ID que utiliza para consultar o estado da operação.This method returns an ID that you use to query the status of the operation.

    /*
     * SNAPSHOT OPERATIONS
     * Copies a person group from one Azure region (or subscription) to another. For example: from the EastUS region to the WestUS.
     * The same process can be used for face lists. 
     * NOTE: the person group in the target region has a new person group ID, so it no longer associates with the source person group.
     */
    public static async Task Snapshot(IFaceClient clientSource, IFaceClient clientTarget, string personGroupId, Guid azureId, Guid targetAzureId)
    {
        Console.WriteLine("========SNAPSHOT OPERATIONS========");
        Console.WriteLine();
    
        // Take a snapshot for the person group that was previously created in your source region.
        var takeSnapshotResult = await clientSource.Snapshot.TakeAsync(SnapshotObjectType.PersonGroup, personGroupId, new[] { azureId }); // add targetAzureId to this array if your target ID is different from your source ID.
        
        // Get operation id from response for tracking the progress of snapshot taking.
        var operationId = Guid.Parse(takeSnapshotResult.OperationLocation.Split('/')[2]);
        Console.WriteLine($"Taking snapshot(operation ID: {operationId})... Started");
    
  2. Em seguida, consultar o ID até que a operação esteja concluída.Next, query the ID until the operation has completed.

    // Wait for taking the snapshot to complete.
    OperationStatus operationStatus = null;
    do
    {
        Thread.Sleep(TimeSpan.FromMilliseconds(1000));
        // Get the status of the operation.
        operationStatus = await clientSource.Snapshot.GetOperationStatusAsync(operationId);
        Console.WriteLine($"Operation Status: {operationStatus.Status}");
    }
    while (operationStatus.Status != OperationStatusType.Succeeded && operationStatus.Status != OperationStatusType.Failed);
    // Confirm the location of the resource where the snapshot is taken and its snapshot ID
    var snapshotId = Guid.Parse(operationStatus.ResourceLocation.Split('/')[2]);
    Console.WriteLine($"Source region snapshot ID: {snapshotId}");
    Console.WriteLine($"Taking snapshot of person group: {personGroupId}... Done\n");
    
  3. Em seguida, utilize a operação de aplicação para escrever os seus dados faciais na subscrição-alvo.Then use the apply operation to write your face data to your target subscription. Este método também devolve um valor de ID.This method also returns an ID value.

    // Apply the snapshot in target region, with a new ID.
    var newPersonGroupId = Guid.NewGuid().ToString();
    targetPersonGroup = newPersonGroupId;
    
    try
    {
        var applySnapshotResult = await clientTarget.Snapshot.ApplyAsync(snapshotId, newPersonGroupId);
    
        // Get operation id from response for tracking the progress of snapshot applying.
        var applyOperationId = Guid.Parse(applySnapshotResult.OperationLocation.Split('/')[2]);
        Console.WriteLine($"Applying snapshot(operation ID: {applyOperationId})... Started");
    
  4. Mais uma vez, consulta o novo ID até que a operação esteja concluída.Again, query the new ID until the operation has completed.

    // Apply the snapshot in target region, with a new ID.
    var newPersonGroupId = Guid.NewGuid().ToString();
    targetPersonGroup = newPersonGroupId;
    
    try
    {
        var applySnapshotResult = await clientTarget.Snapshot.ApplyAsync(snapshotId, newPersonGroupId);
    
        // Get operation id from response for tracking the progress of snapshot applying.
        var applyOperationId = Guid.Parse(applySnapshotResult.OperationLocation.Split('/')[2]);
        Console.WriteLine($"Applying snapshot(operation ID: {applyOperationId})... Started");
    
  5. Por fim, complete o bloco de tentativa/captura e termine o método.Finally, complete the try/catch block and finish the method.

        catch (Exception e)
        {
            throw new ApplicationException("Do you have a second Face resource in Azure? " +
                "It's needed to transfer the person group to it for the Snapshot example.", e);
        }
    }
    

Neste momento, o seu novo objeto PersonGroup deve ter os mesmos dados que o original e deve estar acessível a partir da sua nova subscrição (target) Azure Face.At this point, your new PersonGroup object should have the same data as the original one and should be accessible from your new (target) Azure Face subscription.

Executar a aplicaçãoRun the application

Executar o pedido do seu diretório de candidaturas com o dotnet run comando.Run the application from your application directory with the dotnet run command.

dotnet run

Limpar recursosClean up resources

Se pretender limpar e remover uma subscrição dos Serviços Cognitivos, pode eliminar o grupo de recursos ou recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. A eliminação do grupo de recursos também elimina quaisquer outros recursos que lhe sejam associados.Deleting the resource group also deletes any other resources associated with it.

Se criou um PersonGroup neste arranque rápido e pretende eliminá-lo, execute o seguinte código no seu programa:If you created a PersonGroup in this quickstart and you want to delete it, run the following code in your program:

// At end, delete person groups in both regions (since testing only)
Console.WriteLine("========DELETE PERSON GROUP========");
Console.WriteLine();
DeletePersonGroup(client, sourcePersonGroup).Wait();

Defina o método de eliminação com o seguinte código:Define the deletion method with the following code:

/*
 * DELETE PERSON GROUP
 * After this entire example is executed, delete the person group in your Azure account,
 * otherwise you cannot recreate one with the same name (if running example repeatedly).
 */
public static async Task DeletePersonGroup(IFaceClient client, String personGroupId)
{
    await client.PersonGroup.DeleteAsync(personGroupId);
    Console.WriteLine($"Deleted the person group {personGroupId}.");
}

Além disso, se migrar dados utilizando a funcionalidade Snapshot neste arranque rápido, também terá de eliminar o PersonGroup guardado para a subscrição-alvo.Additionally, if you migrated data using the Snapshot feature in this quickstart, you'll also need to delete the PersonGroup saved to the target subscription.

DeletePersonGroup(clientTarget, targetPersonGroup).Wait();
Console.WriteLine();

Passos seguintesNext steps

Neste arranque rápido, aprendeu a usar a biblioteca Face para .NET para fazer tarefas de base.In this quickstart, you learned how to use the Face library for .NET to do basis tasks. Em seguida, explore a documentação de referência para saber mais sobre a biblioteca.Next, explore the reference documentation to learn more about the library.

Começa com a biblioteca de clientes Face para python.Get started with the Face client library for Python. Siga estes passos para instalar a embalagem e experimente o código de exemplo para tarefas básicas.Follow these steps to install the package and try out the example code for basic tasks. O serviço Face fornece-lhe acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Utilize a biblioteca do cliente Face para Python para:Use the Face client library for Python to:

  • Detetar rostos numa imagemDetect faces in an image
  • Encontrar rostos semelhantesFind similar faces
  • Criar e treinar um grupo de pessoasCreate and train a person group
  • Identificar um rostoIdentify a face
  • Verificar rostosVerify faces
  • Tire uma foto para a migração de dadosTake a snapshot for data migration

Documentação de referência | Código fonte da biblioteca | Pacote (PiPy) | AmostrasReference documentation | Library source code | Package (PiPy) | Samples

Pré-requisitosPrerequisites

  • Python 3.xPython 3.x
  • Subscrição Azure - Crie uma gratuitamenteAzure subscription - Create one for free
  • Assim que tiver a subscrição do Azure, Azure para obter a sua chave e ponto final.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. Depois de implementar, clique em Ir para o recurso.After it deploys, click Go to resource.
    • Necessitará da chave e ponto final do recurso que criar para ligar a sua aplicação à API face.You will need the key and endpoint from the resource you create to connect your application to the Face API. Colará a chave e o ponto final no código abaixo mais tarde no arranque rápido.You'll paste your key and endpoint into the code below later in the quickstart.
    • Pode utilizar o nível de preços gratuitos F0 para experimentar o serviço e fazer upgrade mais tarde para um nível pago para produção.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Depois de obter uma chave e ponto final, crie variáveis ambientais para a chave e ponto final, nomeado FACE_SUBSCRIPTION_KEY FACE_ENDPOINT e, respectivamente.After you get a key and endpoint, create environment variables for the key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT, respectively.

ConfiguraçãoSetting up

Criar uma aplicação Python novaCreate a new Python application

Crie um novo script Python — quickstart-file.py, por exemplo.Create a new Python script—quickstart-file.py, for example. Em seguida, abra-o no seu editor preferido ou IDE e importe as seguintes bibliotecas.Then open it in your preferred editor or IDE and import the following libraries.

import asyncio
import io
import glob
import os
import sys
import time
import uuid
import requests
from urllib.parse import urlparse
from io import BytesIO
from PIL import Image, ImageDraw
from azure.cognitiveservices.vision.face import FaceClient
from msrest.authentication import CognitiveServicesCredentials
from azure.cognitiveservices.vision.face.models import TrainingStatusType, Person, SnapshotObjectType, OperationStatusType

Em seguida, crie variáveis para o ponto final e chave Azure do seu recurso.Then, create variables for your resource's Azure endpoint and key.

# Set the FACE_SUBSCRIPTION_KEY environment variable with your key as the value.
# This key will serve all examples in this document.
KEY = os.environ['FACE_SUBSCRIPTION_KEY']

# Set the FACE_ENDPOINT environment variable with the endpoint from your Face service in Azure.
# This endpoint will be used in all examples in this quickstart.
ENDPOINT = os.environ['FACE_ENDPOINT']

Nota

Se criou a variável ambiental depois de ter lançado a aplicação, terá de fechar e reabrir o editor, o IDE ou a shell que a executa para aceder à variável.If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable.

Instalar a biblioteca do clienteInstall the client library

Pode instalar a biblioteca do cliente com:You can install the client library with:

pip install --upgrade azure-cognitiveservices-vision-face

Modelo de objetoObject model

As seguintes aulas e interfaces lidam com algumas das principais características da biblioteca cliente Face Python.The following classes and interfaces handle some of the major features of the Face Python client library.

NameName DescriptionDescription
FaceClientFaceClient Esta classe representa a sua autorização para usar o serviço Face, e precisa dele para toda a funcionalidade Face.This class represents your authorization to use the Face service, and you need it for all Face functionality. Você instantanea-o com as suas informações de subscrição, e você usá-lo para produzir instâncias de outras classes.You instantiate it with your subscription information, and you use it to produce instances of other classes.
Operações faciaisFaceOperations Esta classe lida com as tarefas básicas de deteção e reconhecimento que pode fazer com rostos humanos.This class handles the basic detection and recognition tasks that you can do with human faces.
Face detetadoDetectedFace Esta classe representa todos os dados que foram detetados a partir de um único rosto numa imagem.This class represents all of the data that was detected from a single face in an image. Pode usá-lo para obter informações detalhadas sobre o rosto.You can use it to retrieve detailed information about the face.
Operações FaceListFaceListOperations Esta classe gere as construções FaceList armazenadas em nuvem, que armazenam um conjunto variado de rostos.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonOperaçõesPersonGroupPersonOperations Esta classe gere as construções de Pessoas armazenadas em nuvem, que armazenam um conjunto de rostos que pertencem a uma única pessoa.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupOperaçõesPersonGroupOperations Esta classe gere as construções do PersonGroup armazenadas na nuvem, que armazenam um conjunto de objetos pessoais variados.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
Operações ShapshotShapshotOperations Esta classe gere a funcionalidade Snapshot; pode usá-lo para guardar temporariamente todos os seus dados faciais baseados na nuvem e migrar esses dados para uma nova subscrição do Azure.This class manages the Snapshot functionality; you can use it to temporarily save all of your cloud-based face data and migrate that data to a new Azure subscription.

Exemplos de códigoCode examples

Estes fragmentos de código mostram-lhe como fazer as seguintes tarefas com a biblioteca do cliente Face para Python:These code snippets show you how to do the following tasks with the Face client library for Python:

Autenticar o clienteAuthenticate the client

Nota

Este quickstart assume que criou uma variável ambiental para a sua chave Face, chamada FACE_SUBSCRIPTION_KEY .This quickstart assumes you've created an environment variable for your Face key, named FACE_SUBSCRIPTION_KEY.

Instantiar um cliente com o seu ponto final e chave.Instantiate a client with your endpoint and key. Crie um objeto CognitiveServicesCredentials com a sua chave e use-o com o seu ponto final para criar um objeto FaceClient.Create a CognitiveServicesCredentials object with your key, and use it with your endpoint to create a FaceClient object.

# Create an authenticated FaceClient.
face_client = FaceClient(ENDPOINT, CognitiveServicesCredentials(KEY))

Detetar rostos numa imagemDetect faces in an image

O seguinte código deteta um rosto numa imagem remota.The following code detects a face in a remote image. Imprime o ID do rosto detetado na consola e também o armazena na memória do programa.It prints the detected face's ID to the console and also stores it in program memory. Depois, deteta os rostos numa imagem com várias pessoas e imprime os seus IDs para a consola também.Then, it detects the faces in an image with multiple people and prints their IDs to the console as well. Ao alterar os parâmetros do método detect_with_url, pode retornar informações diferentes com cada objeto DetectedFace.By changing the parameters in the detect_with_url method, you can return different information with each DetectedFace object.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedy---mini-biography.jpg'
single_image_name = os.path.basename(single_face_image_url)
detected_faces = face_client.face.detect_with_url(url=single_face_image_url)
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Display the detected face ID in the first single-face image.
# Face IDs are used for comparison to faces (their IDs) detected in other images.
print('Detected face ID from', single_image_name, ':')
for face in detected_faces: print (face.face_id)
print()

# Save this ID for use in Find Similar
first_image_face_ID = detected_faces[0].face_id

Consulte o código de amostra no GitHub para mais cenários de deteção.See the sample code on GitHub for more detection scenarios.

Rostos de exibição e molduraDisplay and frame faces

O código seguinte produz a imagem dada para o visor e desenha retângulos em torno dos rostos, utilizando a propriedade DetectedFace.faceRectangle.The following code outputs the given image to the display and draws rectangles around the faces, using the DetectedFace.faceRectangle property.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/detection1.jpg'
single_image_name = os.path.basename(single_face_image_url)
detected_faces = face_client.face.detect_with_url(url=single_face_image_url)
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Convert width height to a point in a rectangle
def getRectangle(faceDictionary):
    rect = faceDictionary.face_rectangle
    left = rect.left
    top = rect.top
    right = left + rect.width
    bottom = top + rect.height
    
    return ((left, top), (right, bottom))


# Download the image from the url
response = requests.get(single_face_image_url)
img = Image.open(BytesIO(response.content))

# For each face returned use the face rectangle and draw a red box.
print('Drawing rectangle around face... see popup for results.')
draw = ImageDraw.Draw(img)
for face in detected_faces:
    draw.rectangle(getRectangle(face), outline='red')

# Display the image in the users default image browser.
img.show()

Uma jovem mulher com um retângulo vermelho desenhado ao redor do rosto

Encontrar rostos semelhantesFind similar faces

O código seguinte pega num único rosto detetado e procura um conjunto de outras caras para encontrar fósforos.The following code takes a single detected face and searches a set of other faces to find matches. Quando encontra uma correspondência, imprime as coordenadas do retângulo da face compatível com a consola.When it finds a match, it prints the rectangle coordinates of the matched face to the console.

Encontrar fósforosFind matches

Em primeiro lugar, executar o código na secção acima(Detetar rostos numa imagem)para guardar uma referência a um único rosto.First, run the code in the above section (Detect faces in an image) to save a reference to a single face. Em seguida, executar o seguinte código para obter referências a várias faces em uma imagem de grupo.Then run the following code to get references to several faces in a group image.

# Detect the faces in an image that contains multiple faces
# Each detected face gets assigned a new ID
multi_face_image_url = "http://www.historyplace.com/kennedy/president-family-portrait-closeup.jpg"
multi_image_name = os.path.basename(multi_face_image_url)
detected_faces2 = face_client.face.detect_with_url(url=multi_face_image_url)

Em seguida, adicione o seguinte bloco de código para encontrar as instâncias da primeira face no grupo.Then add the following code block to find instances of the first face in the group. Consulte o método find_similar para aprender a modificar este comportamento.See the find_similar method to learn how to modify this behavior.

# Search through faces detected in group image for the single face from first image.
# First, create a list of the face IDs found in the second image.
second_image_face_IDs = list(map(lambda x: x.face_id, detected_faces2))
# Next, find similar face IDs like the one detected in the first image.
similar_faces = face_client.face.find_similar(face_id=first_image_face_ID, face_ids=second_image_face_IDs)
if not similar_faces[0]:
    print('No similar faces found in', multi_image_name, '.')

Utilize o seguinte código para imprimir os detalhes da correspondência na consola.Use the following code to print the match details to the console.

# Print the details of the similar faces detected
print('Similar faces found in', multi_image_name + ':')
for face in similar_faces:
    first_image_face_ID = face.face_id
    # The similar face IDs of the single face image and the group image do not need to match, 
    # they are only used for identification purposes in each image.
    # The similar faces are matched using the Cognitive Services algorithm in find_similar().
    face_info = next(x for x in detected_faces2 if x.face_id == first_image_face_ID)
    if face_info:
        print('  Face ID: ', first_image_face_ID)
        print('  Face rectangle:')
        print('    Left: ', str(face_info.face_rectangle.left))
        print('    Top: ', str(face_info.face_rectangle.top))
        print('    Width: ', str(face_info.face_rectangle.width))
        print('    Height: ', str(face_info.face_rectangle.height))

Criar e treinar um grupo de pessoasCreate and train a person group

O código a seguir cria um PersonGroup com três objetos Pessoais diferentes.The following code creates a PersonGroup with three different Person objects. Associa cada Pessoa a um conjunto de imagens de exemplo, e depois treina para ser capaz de reconhecer cada pessoa.It associates each Person with a set of example images, and then it trains to be able to recognize each person.

Criar Grupo de PessoasCreate PersonGroup

Para passar por este cenário, é necessário guardar as seguintes imagens para o diretório de raiz do seu projeto: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images .To step through this scenario, you need to save the following images to the root directory of your project: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

Este grupo de imagens contém três conjuntos de imagens faciais correspondentes a três pessoas diferentes.This group of images contains three sets of face images corresponding to three different people. O código definirá três objetos pessoais e associar-os-á a ficheiros de imagem que começam com woman , e man child .The code will define three Person objects and associate them with image files that start with woman, man, and child.

Uma vez configuradas as suas imagens, defina uma etiqueta no topo do seu script para o objeto PersonGroup que irá criar.Once you've set up your images, define a label at the top of your script for the PersonGroup object you'll create.

# Used in the Person Group Operations,  Snapshot Operations, and Delete Person Group examples.
# You can call list_person_groups to print a list of preexisting PersonGroups.
# SOURCE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
PERSON_GROUP_ID = 'my-unique-person-group'

# Used for the Snapshot and Delete Person Group examples.
TARGET_PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)

Em seguida, adicione o seguinte código na parte inferior do seu script.Then add the following code to the bottom of your script. Este código cria um PersonGroup e três objetos pessoais.This code creates a PersonGroup and three Person objects.

'''
Create the PersonGroup
'''
# Create empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
print('Person group:', PERSON_GROUP_ID)
face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID)

# Define woman friend
woman = face_client.person_group_person.create(PERSON_GROUP_ID, "Woman")
# Define man friend
man = face_client.person_group_person.create(PERSON_GROUP_ID, "Man")
# Define child friend
child = face_client.person_group_person.create(PERSON_GROUP_ID, "Child")

Atribuir rostos a PessoasAssign faces to Persons

O código seguinte classifica as suas imagens pelo seu prefixo, deteta rostos e atribui os rostos a cada objeto Pessoa.The following code sorts your images by their prefix, detects faces, and assigns the faces to each Person object.

'''
Detect faces and register to correct person
'''
# Find all jpeg images of friends in working directory
woman_images = [file for file in glob.glob('*.jpg') if file.startswith("woman")]
man_images = [file for file in glob.glob('*.jpg') if file.startswith("man")]
child_images = [file for file in glob.glob('*.jpg') if file.startswith("child")]

# Add to a woman person
for image in woman_images:
    w = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, woman.person_id, w)

# Add to a man person
for image in man_images:
    m = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, man.person_id, m)

# Add to a child person
for image in child_images:
    ch = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, child.person_id, ch)

Grupo de Pessoas do ComboioTrain PersonGroup

Uma vez atribuídos rostos, deve treinar o PersonGroup para que possa identificar as características visuais associadas a cada um dos seus objetos Pessoais.Once you've assigned faces, you must train the PersonGroup so that it can identify the visual features associated with each of its Person objects. O código a seguir chama o método do comboio assíncronos e sonda o resultado, imprimindo o estado à consola.The following code calls the asynchronous train method and polls the result, printing the status to the console.

'''
Train PersonGroup
'''
print()
print('Training the person group...')
# Train the person group
face_client.person_group.train(PERSON_GROUP_ID)

while (True):
    training_status = face_client.person_group.get_training_status(PERSON_GROUP_ID)
    print("Training status: {}.".format(training_status.status))
    print()
    if (training_status.status is TrainingStatusType.succeeded):
        break
    elif (training_status.status is TrainingStatusType.failed):
        sys.exit('Training the person group has failed.')
    time.sleep(5)

Identificar um rostoIdentify a face

O código seguinte tira uma imagem com múltiplas faces e procura encontrar a identidade de cada pessoa na imagem.The following code takes an image with multiple faces and looks to find the identity of each person in the image. Compara cada rosto detetado a um PersonGroup, uma base de dados de diferentes objetos pessoais cujas características faciais são conhecidas.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known.

Importante

Para executar este exemplo, primeiro deve executar o código em Criar e treinar um grupo de pessoas.In order to run this example, you must first run the code in Create and train a person group.

Obtenha uma imagem de testeGet a test image

O seguinte código olha na raiz do seu projeto para uma imagemtest-image-person-group.jpg e deteta os rostos na imagem.The following code looks in the root of your project for an image test-image-person-group.jpg and detects the faces in the image. Pode encontrar esta imagem com as imagens utilizadas para a gestão do PersonGroup: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images .You can find this image with the images used for PersonGroup management: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

'''
Identify a face against a defined PersonGroup
'''
# Group image for testing against
group_photo = 'test-image-person-group.jpg'
IMAGES_FOLDER = os.path.join(os.path.dirname(os.path.realpath(__file__)))
# Get test image
test_image_array = glob.glob(os.path.join(IMAGES_FOLDER, group_photo))
image = open(test_image_array[0], 'r+b')

# Detect faces
face_ids = []
faces = face_client.face.detect_with_stream(image)
for face in faces:
    face_ids.append(face.face_id)

Identificar rostosIdentify faces

O método de identificação leva uma série de rostos detetados e compara-os a um PersonGroup.The identify method takes an array of detected faces and compares them to a PersonGroup. Se conseguir combinar um rosto detetado com uma Pessoa, salva o resultado.If it can match a detected face to a Person, it saves the result. Este código imprime resultados detalhados da correspondência para a consola.This code prints detailed match results to the console.

# Identify faces
results = face_client.face.identify(face_ids, PERSON_GROUP_ID)
print('Identifying faces in {}'.format(os.path.basename(image.name)))
if not results:
    print('No person identified in the person group for faces from {}.'.format(os.path.basename(image.name)))
for person in results:
    print('Person for face ID {} is identified in {} with a confidence of {}.'.format(person.face_id, os.path.basename(image.name), person.candidates[0].confidence)) # Get topmost confidence score

Verificar rostosVerify faces

A operação Verificar requer um ID facial e outro ID facial ou um objeto de Pessoa e determina se pertencem à mesma pessoa.The Verify operation takes a face ID and either another face ID or a Person object and determines whether they belong to the same person.

O seguinte código deteta rostos em duas imagens de origem e, em seguida, verifica-os contra um rosto detetado a partir de uma imagem do alvo.The following code detects faces in two source images and then verifies them against a face detected from a target image.

Obtenha imagens de testeGet test images

Os blocos de código que se seguem declaram variáveis que apontam para a origem e imagens-alvo para a operação de verificação.The following code blocks declare variables that will point to the source and target images for the verification operation.

# Base url for the Verify and Facelist/Large Facelist operations
IMAGE_BASE_URL = 'https://csdx.blob.core.windows.net/resources/Face/Images/'
# Create a list to hold the target photos of the same person
target_image_file_names = ['Family1-Dad1.jpg', 'Family1-Dad2.jpg']
# The source photos contain this person
source_image_file_name1 = 'Family1-Dad3.jpg'
source_image_file_name2 = 'Family1-Son1.jpg'

Detetar rostos para verificaçãoDetect faces for verification

O código seguinte deteta rostos na origem e imagens-alvo e guarda-os para variáveis.The following code detects faces in the source and target images and saves them to variables.

# Detect face(s) from source image 1, returns a list[DetectedFaces]
detected_faces1 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name1)
# Add the returned face's face ID
source_image1_id = detected_faces1[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces1), source_image_file_name1))

# Detect face(s) from source image 2, returns a list[DetectedFaces]
detected_faces2 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name2)
# Add the returned face's face ID
source_image2_id = detected_faces2[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces2), source_image_file_name2))

# List for the target face IDs (uuids)
detected_faces_ids = []
# Detect faces from target image url list, returns a list[DetectedFaces]
for image_file_name in target_image_file_names:
    detected_faces = face_client.face.detect_with_url(IMAGE_BASE_URL + image_file_name)
    # Add the returned face's face ID
    detected_faces_ids.append(detected_faces[0].face_id)
    print('{} face(s) detected from image {}.'.format(len(detected_faces), image_file_name))

Obtenha resultados de verificaçãoGet verification results

O código seguinte compara cada uma das imagens de origem com a imagem do alvo e imprime uma mensagem indicando se pertencem à mesma pessoa.The following code compares each of the source images to the target image and prints a message indicating whether they belong to the same person.

# Verification example for faces of the same person. The higher the confidence, the more identical the faces in the images are.
# Since target faces are the same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_same = face_client.face.verify_face_to_face(source_image1_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence)
    if verify_result_same.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence))

# Verification example for faces of different persons.
# Since target faces are same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_diff = face_client.face.verify_face_to_face(source_image2_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence)
    if verify_result_diff.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence))

Tire uma foto para a migração de dadosTake a snapshot for data migration

A funcionalidade Snapshots permite-lhe mover os dados do rosto guardado, como um PersonGrouptreinado, para uma subscrição diferente do Azure Cognitive Services Face.The Snapshots feature lets you move your saved face data, such as a trained PersonGroup, to a different Azure Cognitive Services Face subscription. Pode querer utilizar esta funcionalidade se, por exemplo, criou um objeto do PersonGroup usando uma subscrição gratuita e agora pretende migrar para uma subscrição paga.You may want to use this feature if, for example, you've created a PersonGroup object using a free subscription and now want to migrate it to a paid subscription. Consulte os dados do seu rosto para obter uma visão geral da funcionalidade Snapshots.See the Migrate your face data for a broad overview of the Snapshots feature.

Neste exemplo, migrará o PersonGroup que criou na Create e treinará um grupo de pessoas.In this example, you will migrate the PersonGroup you created in Create and train a person group. Pode completar essa secção primeiro ou utilizar os seus próprios dados face.You can either complete that section first, or use your own Face data construct(s).

Configurar a subscrição-alvoSet up target subscription

Em primeiro lugar, deve ter uma segunda subscrição do Azure com recurso Face; pode fazê-lo seguindo os passos na secção Configuração.First, you must have a second Azure subscription with a Face resource; you can do this by following the steps in the Setting up section.

Em seguida, crie as seguintes variáveis perto do topo do seu script.Then, create the following variables near the top of your script. Também terá de criar novas variáveis ambientais para o ID de subscrição da sua conta Azure, bem como a chave, ponto final e ID de subscrição da sua nova conta (alvo).You'll also need to create new environment variables for the subscription ID of your Azure account, as well as the key, endpoint, and subscription ID of your new (target) account.

'''
Snapshot operations variables
These are only used for the snapshot example. Set your environment variables accordingly.
'''
# Source endpoint, the location/subscription where the original person group is located.
SOURCE_ENDPOINT = ENDPOINT
# Source subscription key. Must match the source endpoint region.
SOURCE_KEY = os.environ['FACE_SUBSCRIPTION_KEY']
# Source subscription ID. Found in the Azure portal in the Overview page of your Face (or any) resource.
SOURCE_ID = os.environ['AZURE_SUBSCRIPTION_ID']
# Person group name that will get created in this quickstart's Person Group Operations example.
SOURCE_PERSON_GROUP_ID = PERSON_GROUP_ID
# Target endpoint. This is your 2nd Face subscription.
TARGET_ENDPOINT = os.environ['FACE_ENDPOINT2']
# Target subscription key. Must match the target endpoint region.
TARGET_KEY = os.environ['FACE_SUBSCRIPTION_KEY2']
# Target subscription ID. It will be the same as the source ID if created Face resources from the same 
# subscription (but moving from region to region). If they are differnt subscriptions, add the other target ID here.
TARGET_ID = os.environ['AZURE_SUBSCRIPTION_ID']
# NOTE: We do not need to specify the target PersonGroup ID here because we generate it with this example.
# Each new location you transfer a person group to will have a generated, new person group ID for that region.

Autenticar cliente alvoAuthenticate target client

Mais tarde no seu script, guarde o seu objeto cliente atual como cliente de origem e, em seguida, autenha um novo objeto de cliente para a subscrição do seu alvo.Later in your script, save your current client object as the source client, and then authenticate a new client object for your target subscription.

'''
Authenticate
'''
# Use your source client already created (it has the person group ID you need in it).
face_client_source = face_client
# Create a new FaceClient instance for your target with authentication.
face_client_target = FaceClient(TARGET_ENDPOINT, CognitiveServicesCredentials(TARGET_KEY))

Use um instantâneoUse a snapshot

O resto das operações instantâneas ocorrem dentro de uma função assíncronea.The rest of the snapshot operations take place within an asynchronous function.

  1. O primeiro passo é tirar o instantâneo, que guarda os dados faciais da sua subscrição original para uma localização temporária na nuvem.The first step is to take the snapshot, which saves your original subscription's face data to a temporary cloud location. Este método devolve um ID que utiliza para consultar o estado da operação.This method returns an ID that you use to query the status of the operation.

    '''
    Snapshot operations in 4 steps
    '''
    async def run():
        # STEP 1, take a snapshot of your person group, then track status.
        # This list must include all subscription IDs from which you want to access the snapshot.
        source_list = [SOURCE_ID, TARGET_ID]
        # You may have many sources, if transferring from many regions
        # remove any duplicates from the list. Passing the same subscription ID more than once causes
        # the Snapshot.take operation to fail.
        source_list = list(dict.fromkeys(source_list))
    
        # Note Snapshot.take is not asynchronous.
        # For information about Snapshot.take see:
        # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L36
        take_snapshot_result = face_client_source.snapshot.take(
            type=SnapshotObjectType.person_group,
            object_id=PERSON_GROUP_ID,
            apply_scope=source_list,
            # Set this to tell Snapshot.take to return the response; otherwise it returns None.
            raw=True
            )
        # Get operation ID from response for tracking
        # Snapshot.type return value is of type msrest.pipeline.ClientRawResponse. See:
        # https://docs.microsoft.com/en-us/python/api/msrest/msrest.pipeline.clientrawresponse?view=azure-python
        take_operation_id = take_snapshot_result.response.headers['Operation-Location'].replace('/operations/', '')
    
        print('Taking snapshot( operation ID:', take_operation_id, ')...')
    
  2. Em seguida, consultar o ID até que a operação esteja concluída.Next, query the ID until the operation has completed.

    # STEP 2, Wait for snapshot taking to complete.
    take_status = await wait_for_operation(face_client_source, take_operation_id)
    
    # Get snapshot id from response.
    snapshot_id = take_status.resource_location.replace ('/snapshots/', '')
    
    print('Snapshot ID:', snapshot_id)
    print('Taking snapshot... Done\n')
    

    Este código faz uso da wait_for_operation função, que deve definir separadamente:This code makes use of the wait_for_operation function, which you should define separately:

    # Helper function that waits and checks status of API call processing.
    async def wait_for_operation(client, operation_id):
        # Track progress of taking the snapshot.
        # Note Snapshot.get_operation_status is not asynchronous.
        # For information about Snapshot.get_operation_status see:
        # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L466
        result = client.snapshot.get_operation_status(operation_id=operation_id)
    
        status = result.status.lower()
        print('Operation status:', status)
        if ('notstarted' == status or 'running' == status):
            print("Waiting 10 seconds...")
            await asyncio.sleep(10)
            result = await wait_for_operation(client, operation_id)
        elif ('failed' == status):
            raise Exception("Operation failed. Reason:" + result.message)
        return result
    
  3. Volta para a tua função assíncronea.Go back to your asynchronous function. Utilize a operação de aplicação para escrever os dados do seu rosto na subscrição do seu alvo.Use the apply operation to write your face data to your target subscription. Este método também devolve um ID.This method also returns an ID.

    # STEP 3, apply the snapshot to target region(s)
    # Snapshot.apply is not asynchronous.
    # For information about Snapshot.apply see:
    # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L366
    apply_snapshot_result = face_client_target.snapshot.apply(
        snapshot_id=snapshot_id,
        # Generate a new UUID for the target person group ID.
        object_id=TARGET_PERSON_GROUP_ID,
        # Set this to tell Snapshot.apply to return the response; otherwise it returns None.
        raw=True
        )
    apply_operation_id = apply_snapshot_result.response.headers['Operation-Location'].replace('/operations/', '')
    print('Applying snapshot( operation ID:', apply_operation_id, ')...')
    
  4. Mais uma vez, utilize wait_for_operation a função para consultar o ID até que a operação esteja concluída.Again, use the wait_for_operation function to query the ID until the operation has completed.

    # STEP 4, wait for applying snapshot process to complete.
    await wait_for_operation(face_client_target, apply_operation_id)
    print('Applying snapshot... Done\n')
    print('End of transfer.')
    print()
    

Uma vez concluídas estes passos, poderá aceder às construções de dados do seu rosto a partir da sua nova subscrição (alvo).Once you've completed these steps, you'll be able to access your face data constructs from your new (target) subscription.

Executar a aplicaçãoRun the application

Execute a aplicação com o python comando no seu ficheiro quickstart.Run the application with the python command on your quickstart file.

python quickstart-file.py

Limpar recursosClean up resources

Se pretender limpar e remover uma subscrição dos Serviços Cognitivos, pode eliminar o grupo de recursos ou recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. A eliminação do grupo de recursos também elimina quaisquer outros recursos que lhe sejam associados.Deleting the resource group also deletes any other resources associated with it.

Se criou um PersonGroup neste arranque rápido e pretende eliminá-lo, execute o seguinte código no seu script:If you created a PersonGroup in this quickstart and you want to delete it, run the following code in your script:

# Delete the main person group.
face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
print("Deleted the person group {} from the source location.".format(PERSON_GROUP_ID))
print()

Se migrar dados utilizando a função Snapshot neste arranque rápido, também terá de eliminar o PersonGroup guardado para a subscrição-alvo.If you migrated data using the Snapshot feature in this quickstart, you'll also need to delete the PersonGroup saved to the target subscription.

# Delete the person group in the target region.
face_client_target.person_group.delete(TARGET_PERSON_GROUP_ID)
print("Deleted the person group {} from the target location.".format(TARGET_PERSON_GROUP_ID))

Passos seguintesNext steps

Neste arranque rápido, aprendeu a usar a biblioteca Face para Python para fazer tarefas de base.In this quickstart, you learned how to use the Face library for Python to do basis tasks. Em seguida, explore a documentação de referência para saber mais sobre a biblioteca.Next, explore the reference documentation to learn more about the library.

Começa com a biblioteca de clientes Face para o Go.Get started with the Face client library for Go. Siga estes passos para instalar a biblioteca e experimente os nossos exemplos para tarefas básicas.Follow these steps to install the library and try out our examples for basic tasks. O serviço Face fornece-lhe acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Utilize a biblioteca do cliente de serviço Face para ir a:Use the Face service client library for Go to:

Documentação de referência | Código fonte da biblioteca | Download SDKReference documentation | Library source code | SDK download

Pré-requisitosPrerequisites

  • A última versão de GoThe latest version of Go
  • Subscrição Azure - Crie uma gratuitamenteAzure subscription - Create one for free
  • Assim que tiver a subscrição do Azure, Azure para obter a sua chave e ponto final.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. Depois de implementar, clique em Ir para o recurso.After it deploys, click Go to resource.
    • Necessitará da chave e ponto final do recurso que criar para ligar a sua aplicação à API face.You will need the key and endpoint from the resource you create to connect your application to the Face API. Colará a chave e o ponto final no código abaixo mais tarde no arranque rápido.You'll paste your key and endpoint into the code below later in the quickstart.
    • Pode utilizar o nível de preços gratuitos F0 para experimentar o serviço e fazer upgrade mais tarde para um nível pago para produção.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • Depois de obter uma chave e ponto final, crie variáveis ambientais para a chave e ponto final, nomeado FACE_SUBSCRIPTION_KEY FACE_ENDPOINT e, respectivamente.After you get a key and endpoint, create environment variables for the key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT, respectively.

ConfiguraçãoSetting up

Criar um diretório de projeto goCreate a Go project directory

Numa janela de consola (cmd, PowerShell, Terminal, Bash), crie um novo espaço de trabalho para o seu projeto Go, nomeado my-app , e navegue até ele.In a console window (cmd, PowerShell, Terminal, Bash), create a new workspace for your Go project, named my-app, and navigate to it.

mkdir -p my-app/{src, bin, pkg}  
cd my-app

O seu espaço de trabalho conterá três pastas:Your workspace will contain three folders:

  • src - Este diretório conterá código fonte e pacotes.src - This directory will contain source code and packages. Quaisquer pacotes instalados com o go get comando estarão nesta pasta.Any packages installed with the go get command will be in this folder.
  • pkg - Este diretório conterá os objetos de embalagem Go compilados.pkg - This directory will contain the compiled Go package objects. Todos estes ficheiros têm uma .a extensão.These files all have a .a extension.
  • bin - Este diretório conterá os ficheiros binários executáveis que são criados quando executa go install .bin - This directory will contain the binary executable files that are created when you run go install.

Dica

Para saber mais sobre a estrutura de um espaço de trabalho Go, consulte a documentação da língua Go.To learn more about the structure of a Go workspace, see the Go language documentation. Este guia inclui informações para a definição $GOPATH e $GOROOT .This guide includes information for setting $GOPATH and $GOROOT.

Instale a biblioteca do cliente para GoInstall the client library for Go

Em seguida, instale a biblioteca do cliente para Go:Next, install the client library for Go:

go get -u github.com/Azure/azure-sdk-for-go/tree/master/services/cognitiveservices/v1.0/face

ou se utilizar o dep, dentro da sua corrida de repo:or if you use dep, within your repo run:

dep ensure -add https://github.com/Azure/azure-sdk-for-go/tree/master/services/cognitiveservices/v1.0/face

Criar uma aplicação GoCreate a Go application

Em seguida, crie um ficheiro no diretório src chamado sample-app.go :Next, create a file in the src directory named sample-app.go:

cd src
touch sample-app.go

Abra sample-app.go no seu IDE preferido ou editor de texto.Open sample-app.go in your preferred IDE or text editor. Em seguida, adicione o nome do pacote e importe as seguintes bibliotecas:Then add the package name and import the following libraries:

package main

import (
    "encoding/json"
    "container/list"
    "context"
    "fmt"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v1.0/face"
    "github.com/Azure/go-autorest/autorest"
    "github.com/satori/go.uuid"
    "io"
    "io/ioutil"
    "log"
    "os"
    "path"
    "strconv"
    "strings"
    "time"
)

Em seguida, começará a adicionar código para realizar diferentes operações de serviço Face.Next, you'll begin adding code to carry out different Face service operations.

Modelo de objetoObject model

As seguintes classes e interfaces lidam com algumas das principais características da biblioteca de clientes do serviço Face Go.The following classes and interfaces handle some of the major features of the Face service Go client library.

NameName DescriptionDescription
BaseCienteBaseClient Esta classe representa a sua autorização para usar o serviço Face, e precisa dele para toda a funcionalidade Face.This class represents your authorization to use the Face service, and you need it for all Face functionality. Você instantanea-o com as suas informações de subscrição, e você usá-lo para produzir instâncias de outras classes.You instantiate it with your subscription information, and you use it to produce instances of other classes.
ClienteClient Esta classe lida com as tarefas básicas de deteção e reconhecimento que pode fazer com rostos humanos.This class handles the basic detection and recognition tasks that you can do with human faces.
Face detetadoDetectedFace Esta classe representa todos os dados que foram detetados a partir de um único rosto numa imagem.This class represents all of the data that was detected from a single face in an image. Pode usá-lo para obter informações detalhadas sobre o rosto.You can use it to retrieve detailed information about the face.
ListCienteListClient Esta classe gere as construções FaceList armazenadas em nuvem, que armazenam um conjunto variado de rostos.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonClientPersonGroupPersonClient Esta classe gere as construções de Pessoas armazenadas em nuvem, que armazenam um conjunto de rostos que pertencem a uma única pessoa.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupClientPersonGroupClient Esta classe gere as construções do PersonGroup armazenadas na nuvem, que armazenam um conjunto de objetos pessoais variados.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
SnapshotClientSnapshotClient Esta classe gere a funcionalidade Snapshot.This class manages the Snapshot functionality. Pode usá-lo para guardar temporariamente todos os seus dados face baseados na nuvem e migrar esses dados para uma nova subscrição do Azure.You can use it to temporarily save all of your cloud-based Face data and migrate that data to a new Azure subscription.

Exemplos de códigoCode examples

Estas amostras de código mostram-lhe como completar tarefas básicas utilizando a biblioteca do cliente de serviço Face para Go:These code samples show you how to complete basic tasks using the Face service client library for Go:

Autenticar o clienteAuthenticate the client

Nota

Este quickstart pressupõe que criou variáveis ambientais para a sua chave Face e ponto final, nomeado FACE_SUBSCRIPTION_KEY e FACE_ENDPOINT respectivamente.This quickstart assumes you've created environment variables for your Face key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT respectively.

Crie uma função principal e adicione-lhe o seguinte código para instantaneaizar um cliente com o seu ponto final e chave.Create a main function and add the following code to it to instantiate a client with your endpoint and key. Cria um objeto CognitiveServicesAuthorizer com a sua chave e utiliza-o com o seu ponto final para criar um objeto Cliente.You create a CognitiveServicesAuthorizer object with your key, and use it with your endpoint to create a Client object. Este código também instantaneamente um objeto de contexto, que é necessário para a criação de objetos do cliente.This code also instantiates a context object, which is needed for the creation of client objects. Também define um local remoto onde algumas das imagens da amostra neste quickstart são encontradas.It also defines a remote location where some of the sample images in this quickstart are found.

func main() {

    // A global context for use in all samples
    faceContext := context.Background()

    // Base url for the Verify and Large Face List examples
    const imageBaseURL = "https://csdx.blob.core.windows.net/resources/Face/Images/"

    /*
    Authenticate
    */
    // Add FACE_SUBSCRIPTION_KEY, FACE_ENDPOINT, and AZURE_SUBSCRIPTION_ID to your environment variables.
    subscriptionKey := os.Getenv("FACE_SUBSCRIPTION_KEY")
    
    // This is also known as the 'source' endpoint for the Snapshot example
    endpoint := os.Getenv("FACE_ENDPOINT")

    // Client used for Detect Faces, Find Similar, and Verify examples.
    client := face.NewClient(endpoint)
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)
    /*
    END - Authenticate
    */

Detetar rostos numa imagemDetect faces in an image

Adicione o seguinte código no seu método principal.Add the following code in your main method. Este código define uma imagem de amostra remota e especifica quais as características do rosto a extrair da imagem.This code defines a remote sample image and specifies which face features to extract from the image. Especifica igualmente qual o modelo de IA a utilizar para extrair dados do ou dos rostos detetados.It also specifies which AI model to use to extract data from the detected face(s). Consulte Especificar um modelo de reconhecimento para obter informações sobre estas opções.See Specify a recognition model for information on these options. Finalmente, o método DetectWithURL faz a operação de deteção facial na imagem e guarda os resultados na memória do programa.Finally, the DetectWithURL method does the face detection operation on the image and saves the results in program memory.

// Detect a face in an image that contains a single face
singleFaceImageURL := "https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedy---mini-biography.jpg" 
singleImageURL := face.ImageURL { URL: &singleFaceImageURL } 
singleImageName := path.Base(singleFaceImageURL)
// Use recognition model 2 for feature extraction. Recognition model 1 is used to simply recogize faces.
recognitionModel02 := face.Recognition02
// Array types chosen for the attributes of Face
attributes := []face.AttributeType {"age", "emotion", "gender"}
returnFaceID := true
returnRecognitionModel := false
returnFaceLandmarks := false

// API call to detect faces in single-faced image, using recognition model 2
detectSingleFaces, dErr := client.DetectWithURL(faceContext, singleImageURL, &returnFaceID, &returnFaceLandmarks, attributes, recognitionModel02, &returnRecognitionModel)
if dErr != nil { log.Fatal(dErr) }

// Dereference *[]DetectedFace, in order to loop through it.
dFaces := *detectSingleFaces.Value

Mostrar dados faciais detetadosDisplay detected face data

O próximo bloco de código pega no primeiro elemento na matriz de objetos DetectedFace e imprime os seus atributos à consola.The next block of code takes the first element in the array of DetectedFace objects and prints its attributes to the console. Se usou uma imagem com múltiplas faces, em vez disso deve iterar através da matriz.If you used an image with multiple faces, you should iterate through the array instead.

fmt.Println("Detected face in (" + singleImageName + ") with ID(s): ")
fmt.Println(dFaces[0].FaceID)
fmt.Println()
// Find/display the age and gender attributes
for _, dFace := range dFaces { 
    fmt.Println("Face attributes:")
    fmt.Printf("  Age: %.0f", *dFace.FaceAttributes.Age) 
    fmt.Println("\n  Gender: " + dFace.FaceAttributes.Gender) 
} 
// Get/display the emotion attribute
emotionStruct := *dFaces[0].FaceAttributes.Emotion
// Convert struct to a map
var emotionMap map[string]float64
result, _ := json.Marshal(emotionStruct)
json.Unmarshal(result, &emotionMap)
// Find the emotion with the highest score (confidence level). Range is 0.0 - 1.0.
var highest float64 
emotion := ""
dScore := -1.0
for name, value := range emotionMap{
    if (value > highest) {
        emotion, dScore = name, value
        highest = value
    }
}
fmt.Println("  Emotion: " + emotion + " (score: " + strconv.FormatFloat(dScore, 'f', 3, 64) + ")")

Encontrar rostos semelhantesFind similar faces

O código seguinte requer um único rosto detetado (fonte) e procura um conjunto de outras faces (alvo) para encontrar fósforos.The following code takes a single detected face (source) and searches a set of other faces (target) to find matches. Quando encontra uma correspondência, imprime o ID da face compatível com a consola.When it finds a match, it prints the ID of the matched face to the console.

Detetar rostos para comparaçãoDetect faces for comparison

Em primeiro lugar, guarde uma referência ao rosto detetado nas faces de Deteção numa secção de imagem.First, save a reference to the face you detected in the Detect faces in an image section. Este rosto será a fonte.This face will be the source.

// Select an ID in single-faced image for comparison to faces detected in group image. Used in Find Similar.
firstImageFaceID := dFaces[0].FaceID

Em seguida, introduza o seguinte código para detetar um conjunto de rostos numa imagem diferente.Then enter the following code to detect a set of faces in a different image. Estes rostos serão o alvo.These faces will be the target.

// Detect the faces in an image that contains multiple faces
groupImageURL := "http://www.historyplace.com/kennedy/president-family-portrait-closeup.jpg"
groupImageName := path.Base(groupImageURL)
groupImage := face.ImageURL { URL: &groupImageURL } 

// API call to detect faces in group image, using recognition model 2. This returns a ListDetectedFace struct.
detectedGroupFaces, dgErr := client.DetectWithURL(faceContext, groupImage, &returnFaceID, &returnFaceLandmarks, nil, recognitionModel02, &returnRecognitionModel)
if dgErr != nil { log.Fatal(dgErr) }
fmt.Println()

// Detect faces in the group image.
// Dereference *[]DetectedFace, in order to loop through it.
dFaces2 := *detectedGroupFaces.Value
// Make slice list of UUIDs
faceIDs := make([]uuid.UUID, len(dFaces2))
fmt.Print("Detected faces in (" + groupImageName + ") with ID(s):\n")
for i, face := range dFaces2 {
    faceIDs[i] = *face.FaceID // Dereference DetectedFace.FaceID
    fmt.Println(*face.FaceID)
}

Encontrar fósforosFind matches

O código seguinte utiliza o método FindSimilar para encontrar todas as faces do alvo que correspondam à face da fonte.The following code uses the FindSimilar method to find all of the target faces that match the source face.

// Add single-faced image ID to struct
findSimilarBody := face.FindSimilarRequest { FaceID: firstImageFaceID, FaceIds: &faceIDs }
// Get the list of similar faces found in the group image of previously detected faces
listSimilarFaces, sErr := client.FindSimilar(faceContext, findSimilarBody)
if sErr != nil { log.Fatal(sErr) }

// The *[]SimilarFace 
simFaces := *listSimilarFaces.Value

O código seguinte imprime os detalhes da correspondência para a consola.The following code prints the match details to the console.

// Print the details of the similar faces detected 
fmt.Print("Similar faces found in (" + groupImageName + ") with ID(s):\n")
var sScore float64
for _, face := range simFaces {
    fmt.Println(face.FaceID)
    // Confidence of the found face with range 0.0 to 1.0.
    sScore = *face.Confidence
    fmt.Println("The similarity confidence: ", strconv.FormatFloat(sScore, 'f', 3, 64))
}

Criar e treinar um grupo de pessoasCreate and train a person group

Para passar por este cenário, é necessário guardar as seguintes imagens para o diretório de raiz do seu projeto: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images .To step through this scenario, you need to save the following images to the root directory of your project: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

Este grupo de imagens contém três conjuntos de imagens de um só rosto que correspondem a três pessoas diferentes.This group of images contains three sets of single-face images that correspond to three different people. The code will define three PersonGroup Person objects and associate them with image files that start with woman , man , and child .The code will define three PersonGroup Person objects and associate them with image files that start with woman, man, and child.

Criar Grupo de PessoasCreate PersonGroup

Depois de descarregar as suas imagens, adicione o seguinte código ao fundo do seu método principal.Once you've downloaded your images, add the following code to the bottom of your main method. Este código autentica um objeto PersonGroupClient e, em seguida, utiliza-o para definir um novo PersonGroup.This code authenticates a PersonGroupClient object and then uses it to define a new PersonGroup.

// Get working directory
root, rootErr := os.Getwd()
if rootErr != nil { log.Fatal(rootErr) }

// Full path to images folder
imagePathRoot := path.Join(root+"\\images\\")

// Authenticate - Need a special person group client for your person group
personGroupClient := face.NewPersonGroupClient(endpoint)
personGroupClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)

// Create the Person Group
// Create an empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
personGroupID := "unique-person-group"
fmt.Println("Person group ID: " + personGroupID)
metadata := face.MetaDataContract { Name: &personGroupID }

// Create the person group
personGroupClient.Create(faceContext, personGroupID, metadata)

Criar pessoas do Grupo de PessoasCreate PersonGroup Persons

The next block of code authenticates a PersonGroupPersonClient and uses it to define three new PersonGroup Person objects.The next block of code authenticates a PersonGroupPersonClient and uses it to define three new PersonGroup Person objects. Estes objetos representam cada uma pessoa no conjunto de imagens.These objects each represent a single person in the set of images.

// Authenticate - Need a special person group person client for your person group person
personGroupPersonClient := face.NewPersonGroupPersonClient(endpoint)
personGroupPersonClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)

// Create each person group person for each group of images (woman, man, child)
// Define woman friend
w := "Woman"
nameWoman := face.NameAndUserDataContract { Name: &w }
// Returns a Person type
womanPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameWoman)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Woman person ID: ")
fmt.Println(womanPerson.PersonID)
// Define man friend
m := "Man"
nameMan := face.NameAndUserDataContract { Name: &m }
// Returns a Person type
manPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameMan)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Man person ID: ")
fmt.Println(manPerson.PersonID)
// Define child friend
ch := "Child"
nameChild := face.NameAndUserDataContract { Name: &ch }
// Returns a Person type
childPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameChild)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Child person ID: ")
fmt.Println(childPerson.PersonID)

Atribuir rostos a PessoasAssign faces to Persons

O código a seguir classifica as imagens pelo seu prefixo, deteta rostos e atribui os rostos a cada objeto persongroup PersonGroup Person, com base no nome do ficheiro de imagem.The following code sorts the images by their prefix, detects faces, and assigns the faces to each respective PersonGroup Person object, based on the image file name.

// Detect faces and register to correct person
// Lists to hold all their person images
womanImages := list.New()
manImages := list.New()
childImages := list.New()

// Collect the local images for each person, add them to their own person group person
images, fErr := ioutil.ReadDir(imagePathRoot)
if fErr != nil { log.Fatal(fErr)}
for _, f := range images {
    path:= (imagePathRoot+f.Name())
    if strings.HasPrefix(f.Name(), "w") {
        var wfile io.ReadCloser
        wfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        womanImages.PushBack(wfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *womanPerson.PersonID, wfile, "", nil)
    }
    if strings.HasPrefix(f.Name(), "m") {
        var mfile io.ReadCloser
        mfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        manImages.PushBack(mfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *manPerson.PersonID, mfile, "", nil)
    }
    if strings.HasPrefix(f.Name(), "ch") {
        var chfile io.ReadCloser
        chfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        childImages.PushBack(chfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *childPerson.PersonID, chfile, "", nil)
    }
}

Grupo de Pessoas do ComboioTrain PersonGroup

Uma vez atribuídos rostos, treina o PersonGroup para que possa identificar as características visuais associadas a cada um dos seus objetos Pessoais.Once you've assigned faces, you train the PersonGroup so it can identify the visual features associated with each of its Person objects. O código a seguir chama o método do comboio assíncronos e sonda o resultado, imprimindo o estado à consola.The following code calls the asynchronous train method and polls the result, printing the status to the console.

// Train the person group
personGroupClient.Train(faceContext, personGroupID)

// Wait for it to succeed in training
for {
    trainingStatus, tErr := personGroupClient.GetTrainingStatus(faceContext, personGroupID)
    if tErr != nil { log.Fatal(tErr) }
    
    if trainingStatus.Status == "succeeded" {
        fmt.Println("Training status:", trainingStatus.Status)
        break
    }
    time.Sleep(2)
}

Identificar um rostoIdentify a face

O código seguinte tira uma imagem com múltiplas faces e procura encontrar a identidade de cada pessoa na imagem.The following code takes an image with multiple faces and looks to find the identity of each person in the image. Compara cada rosto detetado a um PersonGroup, uma base de dados de diferentes objetos pessoais cujas características faciais são conhecidas.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known.

Importante

Para executar este exemplo, primeiro deve executar o código em Criar e treinar um grupo de pessoas.In order to run this example, you must first run the code in Create and train a person group.

Obtenha uma imagem de testeGet a test image

O código que se segue olha na raiz do seu projeto para uma imagem test-image-person-group.jpg e carrega-o na memória do programa.The following code looks in the root of your project for an image test-image-person-group.jpg and loads it into program memory. Pode encontrar esta imagem no mesmo repo que as imagens utilizadas na Create e treinar um grupo de pessoas: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images .You can find this image in the same repo as the images used in Create and train a person group: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

personGroupTestImageName := "test-image-person-group.jpg"
// Use image path root from the one created in person group
personGroupTestImagePath := imagePathRoot
var personGroupTestImage io.ReadCloser
// Returns a ReaderCloser
personGroupTestImage, identErr:= os.Open(personGroupTestImagePath+personGroupTestImageName)
if identErr != nil { log.Fatal(identErr) }

Detetar rostos de origem na imagem de testeDetect source faces in test image

O próximo bloco de código faz a deteção facial comum na imagem de teste para recuperar todos os rostos e guardá-los para uma matriz.The next code block does ordinary face detection on the test image to retrieve all of the faces and save them to an array.

// Detect faces in group test image, using recognition model 1 (default)
returnIdentifyFaceID := true
// Returns a ListDetectedFaces
detectedTestImageFaces, dErr := client.DetectWithStream(faceContext, personGroupTestImage, &returnIdentifyFaceID, nil, nil, face.Recognition01, nil)
if dErr != nil { log.Fatal(dErr) }

// Make list of face IDs from the detection. 
length := len(*detectedTestImageFaces.Value)
testImageFaceIDs := make([]uuid.UUID, length)
// ListDetectedFace is a struct with a Value property that returns a *[]DetectedFace
for i, f := range *detectedTestImageFaces.Value {
    testImageFaceIDs[i] = *f.FaceID
}

Identificar rostosIdentify faces

O método Identificar pega na matriz de rostos detetados e compara-os com o Grupo de Pessoas (definido e treinado na secção anterior).The Identify method takes the array of detected faces and compares them to the given PersonGroup (defined and trained in the earlier section). Se conseguir combinar um rosto detetado com uma pessoa do grupo, guarda o resultado.If it can match a detected face to a Person in the group, it saves the result.

// Identify the faces in the test image with everyone in the person group as a query
identifyRequestBody := face.IdentifyRequest { FaceIds: &testImageFaceIDs, PersonGroupID: &personGroupID }
identifiedFaces, err := client.Identify(faceContext, identifyRequestBody)
if err != nil { log.Fatal(err) }

Este código imprime então resultados de correspondência detalhados para a consola.This code then prints detailed match results to the console.

// Get the result which person(s) were identified
iFaces := *identifiedFaces.Value
for _, person := range iFaces {
    fmt.Println("Person for face ID: " )
    fmt.Print(person.FaceID)
    fmt.Println(" is identified in " + personGroupTestImageName + ".")
}

Verificar rostosVerify faces

A operação Verificar requer um ID facial e outro ID facial ou um objeto de Pessoa e determina se pertencem à mesma pessoa.The Verify operation takes a face ID and either another face ID or a Person object and determines whether they belong to the same person.

O código seguinte deteta rostos em duas imagens de origem e, em seguida, verifica cada uma delas contra um rosto detetado a partir de uma imagem do alvo.The following code detects faces in two source images and then verifies each of them against a face detected from a target image.

Obtenha imagens de testeGet test images

Os blocos de código que se seguem declaram variáveis que apontam para o alvo e imagens de origem para a operação de verificação.The following code blocks declare variables that will point to the target and source images for the verification operation.

// Create a slice list to hold the target photos of the same person
targetImageFileNames :=  make([]string, 2)
targetImageFileNames[0] = "Family1-Dad1.jpg"
targetImageFileNames[1] = "Family1-Dad2.jpg"

// The source photos contain this person, maybe
sourceImageFileName1 := "Family1-Dad3.jpg"
sourceImageFileName2 := "Family1-Son1.jpg"

Detetar rostos para verificaçãoDetect faces for verification

O código seguinte deteta rostos na origem e imagens-alvo e guarda-os para variáveis.The following code detects faces in the source and target images and saves them to variables.

// DetectWithURL parameters
urlSource1 := imageBaseURL + sourceImageFileName1
urlSource2 := imageBaseURL + sourceImageFileName2
url1 :=  face.ImageURL { URL: &urlSource1 }
url2 := face.ImageURL { URL: &urlSource2 }
returnFaceIDVerify := true
returnFaceLandmarksVerify := false
returnRecognitionModelVerify := false
// Recognition model 1 is used to rcognise a face, not extract features from it.
recognitionModel01 := face.Recognition01

// Detect face(s) from source image 1, returns a ListDetectedFace struct
detectedVerifyFaces1, dErrV1 := client.DetectWithURL(faceContext, url1 , &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, recognitionModel01, &returnRecognitionModelVerify)
if dErrV1 != nil { log.Fatal(dErrV1) }
// Dereference the result, before getting the ID
dVFaceIds1 := *detectedVerifyFaces1.Value 
// Get ID of the detected face
imageSource1Id := dVFaceIds1[0].FaceID
fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaceIds1), sourceImageFileName1))

// Detect face(s) from source image 2, returns a ListDetectedFace struct
detectedVerifyFaces2, dErrV2 := client.DetectWithURL(faceContext, url2 , &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, recognitionModel01, &returnRecognitionModelVerify)
if dErrV2 != nil { log.Fatal(dErrV2) }
// Dereference the result, before getting the ID
dVFaceIds2 := *detectedVerifyFaces2.Value 
// Get ID of the detected face
imageSource2Id := dVFaceIds2[0].FaceID
fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaceIds2), sourceImageFileName2))
// Detect faces from each target image url in list. DetectWithURL returns a VerifyResult with Value of list[DetectedFaces]
// Empty slice list for the target face IDs (UUIDs)
var detectedVerifyFacesIds [2]uuid.UUID
for i, imageFileName := range targetImageFileNames {
    urlSource := imageBaseURL + imageFileName 
    url :=  face.ImageURL { URL: &urlSource}
    detectedVerifyFaces, dErrV := client.DetectWithURL(faceContext, url, &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, recognitionModel01, &returnRecognitionModelVerify)
    if dErrV != nil { log.Fatal(dErrV) }
    // Dereference *[]DetectedFace from Value in order to loop through it.
    dVFaces := *detectedVerifyFaces.Value
    // Add the returned face's face ID
    detectedVerifyFacesIds[i] = *dVFaces[0].FaceID
    fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaces), imageFileName))
}

Obtenha resultados de verificaçãoGet verification results

O código seguinte compara cada uma das imagens de origem com a imagem do alvo e imprime uma mensagem indicando se pertencem à mesma pessoa.The following code compares each of the source images to the target image and prints a message indicating whether they belong to the same person.

// Verification example for faces of the same person. The higher the confidence, the more identical the faces in the images are.
// Since target faces are the same person, in this example, we can use the 1st ID in the detectedVerifyFacesIds list to compare.
verifyRequestBody1 := face.VerifyFaceToFaceRequest{ FaceID1: imageSource1Id, FaceID2: &detectedVerifyFacesIds[0] }
verifyResultSame, vErrSame := client.VerifyFaceToFace(faceContext, verifyRequestBody1)
if vErrSame != nil { log.Fatal(vErrSame) }

fmt.Println()

// Check if the faces are from the same person.
if (*verifyResultSame.IsIdentical) {
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of the same person, with confidence %v", 
    sourceImageFileName1, targetImageFileNames[0], strconv.FormatFloat(*verifyResultSame.Confidence, 'f', 3, 64)))
} else {
    // Low confidence means they are more differant than same.
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of a different person, with confidence %v", 
    sourceImageFileName1, targetImageFileNames[0], strconv.FormatFloat(*verifyResultSame.Confidence, 'f', 3, 64)))
}

// Verification example for faces of different persons. 
// Since target faces are same person, in this example, we can use the 1st ID in the detectedVerifyFacesIds list to compare.
verifyRequestBody2 := face.VerifyFaceToFaceRequest{ FaceID1: imageSource2Id, FaceID2: &detectedVerifyFacesIds[0] }
verifyResultDiff, vErrDiff := client.VerifyFaceToFace(faceContext, verifyRequestBody2)
if vErrDiff != nil { log.Fatal(vErrDiff) }
// Check if the faces are from the same person.
if (*verifyResultDiff.IsIdentical) {
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of the same person, with confidence %v", 
    sourceImageFileName2, targetImageFileNames[0], strconv.FormatFloat(*verifyResultDiff.Confidence, 'f', 3, 64)))
} else {
    // Low confidence means they are more differant than same.
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of a different person, with confidence %v", 
    sourceImageFileName2, targetImageFileNames[0], strconv.FormatFloat(*verifyResultDiff.Confidence, 'f', 3, 64)))
}

Tire uma foto para a migração de dadosTake a snapshot for data migration

A funcionalidade Snapshots permite-lhe mover os dados do rosto guardado, como um PersonGrouptreinado, para uma subscrição diferente do Azure Cognitive Services Face.The Snapshots feature lets you move your saved face data, such as a trained PersonGroup, to a different Azure Cognitive Services Face subscription. Pode utilizar esta funcionalidade se, por exemplo, tiver criado um objeto Do PersonGroup utilizando uma subscrição gratuita e pretender agora emigrá-la para uma subscrição paga.You might use this feature if, for example, you've created a PersonGroup object using a free subscription and now want to migrate it to a paid subscription. Consulte os dados do seu rosto para obter uma visão geral da funcionalidade Snapshots.See the Migrate your face data for a broad overview of the Snapshots feature.

Neste exemplo, migrará o PersonGroup que criou na Create e treinará um grupo de pessoas.In this example, you'll migrate the PersonGroup you created in Create and train a person group. Pode completar essa secção primeiro ou utilizar os seus próprios dados face.You can either complete that section first, or use your own Face data construct(s).

Configurar a subscrição-alvoSet up target subscription

Em primeiro lugar, deve ter uma segunda subscrição do Azure com recurso Face; pode fazê-lo repetindo os passos na secção Configuração.First, you must have a second Azure subscription with a Face resource; you can do this by repeating the steps in the Set up section.

Em seguida, crie as seguintes variáveis perto do topo do seu método principal.Then, create the following variables near the top of your main method. Também terá de criar novas variáveis ambientais para o ID de subscrição da sua conta Azure, bem como a chave, ponto final e ID de subscrição da sua nova conta (alvo).You'll also need to create new environment variables for the subscription ID of your Azure account, as well as the key, endpoint, and subscription ID of your new (target) account.

// This key should be from another Face resource with a different region. 
// Used for the Snapshot example only.
targetSubscriptionKey := os.Getenv("FACE_SUBSCRIPTION_KEY2")

// This should have a different region than your source endpoint. used only in Snapshot.
targetEndpoint := os.Getenv("FACE_ENDPOINT2")

// Get your subscription ID (different than the key) from any Face resource in Azure.
azureSubscriptionID, uuidErr := uuid.FromString(os.Getenv("AZURE_SUBSCRIPTION_ID"))

Em seguida, coloque o seu valor de ID de subscrição numa matriz para os próximos passos.Then, put your subscription ID value into an array for the next steps.

// Add your Azure subscription ID(s) to a UUID array.
numberOfSubKeys := 1 
targetUUIDArray := make([]uuid.UUID, numberOfSubKeys)
for i := range targetUUIDArray {
    targetUUIDArray[i] = azureSubscriptionID
}

Autenticar cliente alvoAuthenticate target client

Mais tarde no seu script, guarde o seu objeto cliente original como cliente de origem e, em seguida, autenha um novo objeto cliente para a subscrição do seu alvo.Later in your script, save your original client object as the source client, and then authenticate a new client object for your target subscription.

// Create a client from your source region, where your person group exists. Use for taking the snapshot.
snapshotSourceClient := face.NewSnapshotClient(endpoint)
snapshotSourceClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)
// Create a client for your target region. Use for applying the snapshot.
snapshotTargetClient := face.NewSnapshotClient(targetEndpoint)
snapshotTargetClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(targetSubscriptionKey)

Criar um InstantâneoTake a snapshot

O próximo passo é tirar o instantâneo com o Take, que guarda os dados faciais da sua subscrição original para uma localização temporária na nuvem.The next step is to take the snapshot with Take, which saves your original subscription's face data to a temporary cloud location. Este método devolve um ID que utiliza para consultar o estado da operação.This method returns an ID that you use to query the status of the operation.

// Take snapshot
takeBody := face.TakeSnapshotRequest { Type: face.SnapshotObjectTypePersonGroup, ObjectID: &personGroupID, ApplyScope: &targetUUIDArray }
takeSnapshotResult, takeErr := snapshotSourceClient.Take(faceContext, takeBody)
if takeErr != nil { log.Fatal(takeErr) }
// Get the operations ID
strTakeOperation := strings.ReplaceAll(takeSnapshotResult.Header.Get("Operation-Location"), "/operations/", "")
fmt.Println("Taking snapshot (operations ID: " + strTakeOperation + ")... started")
// Convert string operation ID to UUID
takeOperationID, uuidErr := uuid.FromString(strTakeOperation)
if uuidErr != nil { log.Fatal(uuidErr) }

Em seguida, consultar o ID até que a operação esteja concluída.Next, query the ID until the operation has completed.

// Wait for the snapshot taking to finish
var strSnapshotID string
for {
    takeSnapshotStatus, tErr := snapshotSourceClient.GetOperationStatus(faceContext, takeOperationID)
    if tErr != nil { log.Fatal(tErr) }
    
    if takeSnapshotStatus.Status == "succeeded" {
        fmt.Println("Taking snapshot operation status: ", takeSnapshotStatus.Status)
        strSnapshotID = strings.ReplaceAll(*takeSnapshotStatus.ResourceLocation, "/snapshots/", "")
        break
    }
    time.Sleep(2)
}

// Convert string snapshot to UUID
snapshotID, uuidErr := uuid.FromString(strSnapshotID)
if uuidErr != nil { log.Fatal(uuidErr) }

Aplique o instantâneoApply the snapshot

Utilize a operação Apply para escrever os seus dados faciais recém-carregados para a subscrição do seu destino.Use the Apply operation to write your newly uploaded face data to your target subscription. Este método também devolve um ID.This method also returns an ID.

// Creates a new snapshot instance in your target region. 
// Make sure not to create a new snapshot in your target region with the same name as another one.
applyBody := face.ApplySnapshotRequest { ObjectID: &personGroupID }
applySnapshotResult, applyErr := snapshotTargetClient.Apply(faceContext, snapshotID, applyBody)
if applyErr != nil { log.Fatal(applyErr) }

// Get operation ID from response to track the progress of applying a snapshot.
strApplyOperation := strings.ReplaceAll(applySnapshotResult.Header.Get("Operation-Location"), "/operations/", "")
fmt.Println("Applying snapshot (operations ID: " + strApplyOperation + ")... started")
// Convert operation ID to GUID
applyOperationID, guidErr := uuid.FromString(strApplyOperation)
if guidErr != nil { log.Fatal(guidErr) }

Mais uma vez, consulta o ID até que a operação esteja concluída.Again, query the ID until the operation has completed.

// Wait for the snapshot applying to finish
for {
    applySnapshotStatus, aErr := snapshotTargetClient.GetOperationStatus(faceContext, applyOperationID)
    if aErr != nil { log.Fatal(aErr) }
    
    if applySnapshotStatus.Status == "succeeded" {
        fmt.Println("Taking snapshot operation status: ", applySnapshotStatus.Status)
        break
    }
    time.Sleep(2)
}

Uma vez concluídas estas etapas, pode aceder aos dados do seu rosto a partir da sua nova subscrição (alvo).Once you've completed these steps, you can access your face data constructs from your new (target) subscription.

Executar a aplicaçãoRun the application

Execute a sua aplicação Go com o go run [arguments] comando do seu diretório de candidaturas.Run your Go application with the go run [arguments] command from your application directory.

go run sample-app.go

Limpar recursosClean up resources

Se pretender limpar e remover uma subscrição dos Serviços Cognitivos, pode eliminar o grupo de recursos ou recursos.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. A eliminação do grupo de recursos também elimina quaisquer outros recursos que lhe sejam associados.Deleting the resource group also deletes any other resources associated with it.

Se criou um PersonGroup neste arranque rápido e pretende eliminá-lo, ligue para o método Eliminar.If you created a PersonGroup in this quickstart and you want to delete it, call the Delete method. Se migrar dados utilizando a função Snapshot neste arranque rápido, também terá de eliminar o PersonGroup guardado para a subscrição-alvo.If you migrated data using the Snapshot feature in this quickstart, you'll also need to delete the PersonGroup saved to the target subscription.

Passos seguintesNext steps

Neste arranque rápido, aprendeu a usar a biblioteca Face para ir para fazer tarefas de base.In this quickstart, you learned how to use the Face library for Go to do basis tasks. Em seguida, explore a documentação de referência para saber mais sobre a biblioteca.Next, explore the reference documentation to learn more about the library.