快速入门:使用人脸 REST API 和 C# 检测图像中的人脸Quickstart: Detect faces in an image using the Face REST API and C#

在本快速入门中,请使用 Azure 人脸 REST API 和 C# 检测图像中的人脸。In this quickstart, you will use the Azure Face REST API with C# to detect human faces in an image.

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a Trial before you begin.

先决条件Prerequisites

创建 Visual Studio 项目Create the Visual Studio project

  1. 在 Visual Studio 中创建新的控制台应用 (.NET Framework) 项目并将其命名为 FaceDetectionIn Visual Studio, create a new Console app (.NET Framework) project and name it FaceDetection.
  2. 如果解决方案中有其他项目,请将此项目选为单一启动项目。If there are other projects in your solution, select this one as the single startup project.

添加人脸检测代码Add face detection code

打开新项目的 Program.cs 文件。Open the new project's Program.cs file. 在这里,请添加加载图像和检测人脸所需的代码。Here, you will add the code needed to load images and detect faces.

包括命名空间Include namespaces

将以下 using 语句添加到 Program.cs 文件顶部。Add the following using statements to the top of your Program.cs file.

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

添加必要的字段Add essential fields

添加包含以下字段的 Program 类。Add the Program class containing the following fields. 该数据指定如何连接到人脸服务,以及在何处获取输入数据。This data specifies how to connect to the Face service and where to get the input data. 需使用订阅密钥的值更新 subscriptionKey 字段,并且可能需要更改 uriBase 字符串,使之包含正确的区域标识符(如需包含所有区域终结点的列表,请参阅人脸 API 文档)。You'll need to update the subscriptionKey field with the value of your subscription key, and you may need to change the uriBase string so that it contains the correct region identifier (see the Face API docs for a list of all region endpoints).

namespace DetectFace
{
    class Program
    {

        // Replace <Subscription Key> with your valid subscription key.
        const string subscriptionKey = "<Subscription Key>";

        const string uriBase = "https://api.cognitive.azure.cn/face/v1.0/detect";

接收图像输入Receive image input

将以下代码添加到 Program 类的 Main 方法。Add the following code to the Main method of the Program class. 这样会将一个提示写入到控制台,要求用户输入图像 URL。This writes a prompt to the console asking the user to enter an image URL. 然后,它会调用另一方法 (MakeAnalysisRequest),在该位置处理图像。Then it calls another method, MakeAnalysisRequest, to process the image at that location.

        static void Main(string[] args)
        {

            // Get the path and filename to process from the user.
            Console.WriteLine("Detect faces:");
            Console.Write(
                "Enter the path to an image with faces that you wish to analyze: ");
            string imageFilePath = Console.ReadLine();

            if (File.Exists(imageFilePath))
            {
                try
                {
                    MakeAnalysisRequest(imageFilePath);
                    Console.WriteLine("\nWait a moment for the results to appear.\n");
                }
                catch (Exception e)
                {
                    Console.WriteLine("\n" + e.Message + "\nPress Enter to exit...\n");
                }
            }
            else
            {
                Console.WriteLine("\nInvalid file path.\nPress Enter to exit...\n");
            }
            Console.ReadLine();
        }

调用人脸检测 REST APICall the face detection REST API

将以下方法添加到 Program 类。Add the following method to the Program class. 它构造一个针对人脸 API 的 REST 调用,以便检测远程图像(requestParameters 字符串指定要检索的人脸属性)中的人脸信息。It constructs a REST call to the Face API to detect face information in the remote image (the requestParameters string specifies which face attributes to retrieve). 然后,它将输出数据写入到 JSON 字符串。Then it writes the output data to a JSON string.

将在以下步骤中定义帮助程序方法。You will define the helper methods in the following steps.

        // Gets the analysis of the specified image by using the Face REST API.
        static async void MakeAnalysisRequest(string imageFilePath)
        {
            HttpClient client = new HttpClient();

            // Request headers.
            client.DefaultRequestHeaders.Add(
                "Ocp-Apim-Subscription-Key", subscriptionKey);

            // Request parameters. A third optional parameter is "details".
            string requestParameters = "returnFaceId=true&returnFaceLandmarks=false" +
                "&returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses," +
                "emotion,hair,makeup,occlusion,accessories,blur,exposure,noise";

            // Assemble the URI for the REST API Call.
            string uri = uriBase + "?" + requestParameters;

            HttpResponseMessage response;

            // Request body. Posts a locally stored JPEG image.
            byte[] byteData = GetImageAsByteArray(imageFilePath);

            using (ByteArrayContent content = new ByteArrayContent(byteData))
            {
                // This example uses content type "application/octet-stream".
                // The other content types you can use are "application/json"
                // and "multipart/form-data".
                content.Headers.ContentType =
                    new MediaTypeHeaderValue("application/octet-stream");

                // Execute the REST API call.
                response = await client.PostAsync(uri, content);

                // Get the JSON response.
                string contentString = await response.Content.ReadAsStringAsync();

                // Display the JSON response.
                Console.WriteLine("\nResponse:\n");
                Console.WriteLine(JsonPrettyPrint(contentString));
                Console.WriteLine("\nPress Enter to exit...");
            }
        }

处理输入图像数据Process the input image data

将以下方法添加到 Program 类。Add the following method to the Program class. 这会将指定 URL 中的图像转换为字节数组。This converts the image at the specified URL into a byte array.

        // Returns the contents of the specified file as a byte array.
        static byte[] GetImageAsByteArray(string imageFilePath)
        {
            using (FileStream fileStream =
                new FileStream(imageFilePath, FileMode.Open, FileAccess.Read))
            {
                BinaryReader binaryReader = new BinaryReader(fileStream);
                return binaryReader.ReadBytes((int)fileStream.Length);
            }
        }

分析 JSON 响应Parse the JSON response

将以下方法添加到 Program 类。Add the following method to the Program class. 这会格式化 JSON 输入,使之更加易于读取。This formats the JSON input to be more easily readable. 应用会将该字符串数据写入到控制台。Your app will write this string data to the console. 然后即可关闭类和命名空间。You can then close the class and namespace.

        // Formats the given JSON string by adding line breaks and indents.
        static string JsonPrettyPrint(string json)
        {
            if (string.IsNullOrEmpty(json))
                return string.Empty;

            json = json.Replace(Environment.NewLine, "").Replace("\t", "");

            StringBuilder sb = new StringBuilder();
            bool quote = false;
            bool ignore = false;
            int offset = 0;
            int indentLength = 3;

            foreach (char ch in json)
            {
                switch (ch)
                {
                    case '"':
                        if (!ignore) quote = !quote;
                        break;
                    case '\'':
                        if (quote) ignore = !ignore;
                        break;
                }

                if (quote)
                    sb.Append(ch);
                else
                {
                    switch (ch)
                    {
                        case '{':
                        case '[':
                            sb.Append(ch);
                            sb.Append(Environment.NewLine);
                            sb.Append(new string(' ', ++offset * indentLength));
                            break;
                        case '}':
                        case ']':
                            sb.Append(Environment.NewLine);
                            sb.Append(new string(' ', --offset * indentLength));
                            sb.Append(ch);
                            break;
                        case ',':
                            sb.Append(ch);
                            sb.Append(Environment.NewLine);
                            sb.Append(new string(' ', offset * indentLength));
                            break;
                        case ':':
                            sb.Append(ch);
                            sb.Append(' ');
                            break;
                        default:
                            if (ch != ' ') sb.Append(ch);
                            break;
                    }
                }
            }

            return sb.ToString().Trim();
        }
    }
}

运行应用程序Run the app

成功的响应会以易于读取的 JSON 格式显示人脸数据。A successful response will display Face data in easily readable JSON format. 例如:For example:

[
   {
      "faceId": "f7eda569-4603-44b4-8add-cd73c6dec644",
      "faceRectangle": {
         "top": 131,
         "left": 177,
         "width": 162,
         "height": 162
      },
      "faceAttributes": {
         "smile": 0.0,
         "headPose": {
            "pitch": 0.0,
            "roll": 0.1,
            "yaw": -32.9
         },
         "gender": "female",
         "age": 22.9,
         "facialHair": {
            "moustache": 0.0,
            "beard": 0.0,
            "sideburns": 0.0
         },
         "glasses": "NoGlasses",
         "emotion": {
            "anger": 0.0,
            "contempt": 0.0,
            "disgust": 0.0,
            "fear": 0.0,
            "happiness": 0.0,
            "neutral": 0.986,
            "sadness": 0.009,
            "surprise": 0.005
         },
         "blur": {
            "blurLevel": "low",
            "value": 0.06
         },
         "exposure": {
            "exposureLevel": "goodExposure",
            "value": 0.67
         },
         "noise": {
            "noiseLevel": "low",
            "value": 0.0
         },
         "makeup": {
            "eyeMakeup": true,
            "lipMakeup": true
         },
         "accessories": [

         ],
         "occlusion": {
            "foreheadOccluded": false,
            "eyeOccluded": false,
            "mouthOccluded": false
         },
         "hair": {
            "bald": 0.0,
            "invisible": false,
            "hairColor": [
               {
                  "color": "brown",
                  "confidence": 1.0
               },
               {
                  "color": "black",
                  "confidence": 0.87
               },
               {
                  "color": "other",
                  "confidence": 0.51
               },
               {
                  "color": "blond",
                  "confidence": 0.08
               },
               {
                  "color": "red",
                  "confidence": 0.08
               },
               {
                  "color": "gray",
                  "confidence": 0.02
               }
            ]
         }
      }
   }
]

后续步骤Next steps

在本快速入门中,你创建了一个简单的 .NET 控制台应用程序,该应用程序可以将 REST 调用与 Azure 人脸 API 配合使用,以便检测图像中的人脸并返回其属性。In this quickstart, you created a simple .NET console application that uses REST calls with the Azure Face API to detect faces in an image and return their attributes. 接下来,请浏览人脸 API 参考文档,详细了解支持的方案。Next, explore the Face API reference documentation to learn more about the supported scenarios.