人脸 API

Microsoft认知服务人脸 API 允许检测、识别、分析、组织和标记照片中的人脸。

此连接器在以下产品和区域中可用：

服务	Class	区域
Copilot Studio	标准	所有 Power Automate 区域
逻辑应用程序	标准	所有 逻辑应用区域
Power Apps	标准	所有 Power Apps 区域
Power Automate	标准	所有 Power Automate 区域

联系人​​
Name	Microsoft
URL	Microsoft LogicApps 支持 Microsoft Power Automate 支持 Microsoft Power Apps 支持

连接器元数据
发布者	Microsoft
Website	https://azure.microsoft.com/services/cognitive-services/face/

若要使用此集成，需要在 Azure 门户中使用 认知服务资源 。 你将获得用于对应用程序进行身份验证的终结点和密钥。 若要建立连接，请提供帐户密钥、站点 URL 并选择“ 创建连接”。 有关连接的作成本， 请在此处了解详细信息。

现在，你已准备好开始使用此集成。

使用 Microsoft Entra ID 进行连接

若要使用 Microsoft Entra ID 创建连接，必须将认知服务用户角色添加到帐户才能访问。 若要使用此连接，必须将认知服务资源关联的唯一子域输入到支持作中。

Microsoft Entra ID 身份验证不支持的作

使用 Microsoft Entra ID 身份验证 时，仅支持 V2作。 弃用的作将继续使用 Access Key 身份验证，但如果 与 Microsoft Entra ID 连接一起使用，将失败。

正在创建连接

连接器支持以下身份验证类型：

Api 密钥	Api 密钥	所有区域	可共享
默认值 [已弃用]	此选项仅适用于没有显式身份验证类型的较旧连接，并且仅用于向后兼容性。	所有区域	不可共享

Api 密钥

身份验证 ID：keyBasedAuth

适用：所有区域

Api 密钥

这是可共享的连接。 如果 Power App 与其他用户共享，则连接也会共享。 有关详细信息，请参阅 画布应用的连接器概述 - Power Apps |Microsoft Docs

Name	类型	Description	必选
帐户密钥	securestring	认知服务帐户密钥
网站 URL	字符串	根网站 URL （示例： https://westus.api.cognitive.microsoft.com）

默认值 [已弃用]

适用：所有区域

此选项仅适用于没有显式身份验证类型的较旧连接，并且仅用于向后兼容性。

这是不可共享的连接。 如果 Power App 与另一个用户共享，系统会提示其他用户显式创建新连接。

Name	类型	Description	必选
API 密钥	securestring	API 密钥	True
网站 URL	字符串	根网站 URL （示例： https://westus.api.cognitive.microsoft.com ） 。如果未指定网站 URL，则默认为“”。https://westus.api.cognitive.microsoft.com

限制

名称	调用	续订期
每个连接的 API 调用数	1200	60 秒

操作

从人脸查找人员	验证两张人脸是否属于同一个人，或者一张人脸是否属于一个人。
从人脸查找人员 （V2）	验证两张人脸是否属于同一个人，或者一张人脸是否属于一个人。
创建人员	在指定人员组中创建新人员。
创建人员组	使用指定的 personGroupId、名称和用户提供的 userData 创建新的人员组。
创建人员组 （V2）	使用指定的 personGroupId、名称和用户提供的 userData 创建新的人员组。
创建人员（V2）	在指定人员组中创建新人员。
创建人脸列表	使用用户指定的 faceListId、名称和可选 userData 创建空人脸列表。
创建人脸列表 （V2）	使用用户指定的 faceListId、名称和可选 userData 创建空人脸列表。
将人脸添加到人脸列表	将人脸添加到人脸列表。
将人脸添加到人脸列表 （V2）	将人脸添加到人脸列表。
检测人脸	检测图像中的人脸并返回人脸位置，还可以选择使用 faceId、地标和属性。
检测人脸 （V2）	检测图像中的人脸并返回人脸位置，还可以选择使用 faceId、地标和属性。
添加人脸	向人员添加代表人脸进行标识。
添加人脸 （V2）	向人员添加代表人脸进行标识。
获取人员	检索人员的信息，包括已注册的持久人脸、名称和 userData。
获取人员组	检索人员组的信息，包括其名称和 userData。
获取人员组 （V2）	检索人员组的信息，包括其名称和 userData。
获取人员（V2）	检索人员的信息，包括已注册的持久人脸、名称和 userData。
获取人脸	检索有关 persistedFaceId、personId 及其所属 personGroupId 指定的持久人脸的信息。
获取人脸 （V2）	检索有关 persistedFaceId、personId 及其所属 personGroupId 指定的持久人脸的信息。
获取人脸列表	检索人脸列表的信息，包括 faceListId、name、userData 和人脸列表中的人脸。
获取人脸列表 （V2）	检索人脸列表的信息，包括 faceListId、name、userData 和人脸列表中的人脸。

从人脸查找人员

操作 ID:

Verify

验证两张人脸是否属于同一个人，或者一张人脸是否属于一个人。

参数

名称	密钥	必需	类型	说明
人脸 ID	faceId	True	string	检测到的人脸的唯一 faceId。 将在检测调用后 24 小时过期。
人员组 ID	personGroupId	True	string	在人脸 API 中创建的人员组 ID - 创建人员组作。
人员 ID	personId	True	string	在人脸 API 中创建的人员 ID - 创建人员作。

返回

Body

VerifyResponse

从人脸查找人员 （V2）

操作 ID:

VerifyV2

验证两张人脸是否属于同一个人，或者一张人脸是否属于一个人。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人脸 ID	faceId	True	string	检测到的人脸的唯一 faceId。 将在检测调用后 24 小时过期。
人员组 ID	personGroupId	True	string	在人脸 API 中创建的人员组 ID - 创建人员组作。
人员 ID	personId	True	string	在人脸 API 中创建的人员 ID - 创建人员作。

返回

Body

VerifyResponse

创建人员

操作 ID:

CreatePerson

在指定人员组中创建新人员。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	指定要创建该人员的目标人员组。
Name	name	True	string	目标人员的显示名称。 最大长度为 128。
用户数据	userData		string	附加到人员的用户提供数据的可选字段。 大小限制为 16KB。

返回

Body

CreatePersonResponse

创建人员组

操作 ID:

CreatePersonGroup

使用指定的 personGroupId、名称和用户提供的 userData 创建新的人员组。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	新人员组 ID（有效字符包括数字、小写字母、“-”和“_”）
Name	name	True	string	人员组显示名称。 最大长度为 128。
用户数据	userData		string	附加到人员组的用户提供的数据。 大小限制为 16KB。

创建人员组 （V2）

操作 ID:

CreatePersonGroupV2

使用指定的 personGroupId、名称和用户提供的 userData 创建新的人员组。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	新人员组 ID（有效字符包括数字、小写字母、“-”和“_”）
Name	name	True	string	人员组显示名称。 最大长度为 128。
用户数据	userData		string	附加到人员组的用户提供的数据。 大小限制为 16KB。

创建人员（V2）

操作 ID:

CreatePersonV2

在指定人员组中创建新人员。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	指定要创建该人员的目标人员组。
Name	name	True	string	目标人员的显示名称。 最大长度为 128。
用户数据	userData		string	附加到人员的用户提供数据的可选字段。 大小限制为 16KB。

返回

Body

CreatePersonResponse

创建人脸列表

操作 ID:

CreateFaceList

使用用户指定的 faceListId、名称和可选 userData 创建空人脸列表。

参数

名称	密钥	必需	类型	说明
人脸列表 ID	faceListId	True	string	有效字符是小写字母或数字或“-”或“_”，最大长度为 64
人脸列表名称	name	True	string	创建的人脸列表的名称，最大长度为 128。
用户数据	userData		string	人脸列表的可选用户定义数据。 长度不应超过 16KB。

创建人脸列表 （V2）

操作 ID:

CreateFaceListV2

使用用户指定的 faceListId、名称和可选 userData 创建空人脸列表。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人脸列表 ID	faceListId	True	string	有效字符是小写字母或数字或“-”或“_”，最大长度为 64
人脸列表名称	name	True	string	创建的人脸列表的名称，最大长度为 128。
用户数据	userData		string	人脸列表的可选用户定义数据。 长度不应超过 16KB。

将人脸添加到人脸列表

操作 ID:

AddFaceToFaceList

将人脸添加到人脸列表。

参数

名称	密钥	必需	类型	说明
图像 URL	url		string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP
目标人脸	targetFace		string	一个人脸矩形，用于指定要添加到人员的目标人脸，格式为 targetFace=left、top、width、height
用户数据	userData		string	要出于任何目的添加的目标人脸的用户指定数据。 最大长度为 1KB。
人脸列表 ID	faceListId	True	string	有效字符为小写字母或数字或“-”或“_”，最大长度为 64。

返回

Body

AddPersonFaceResponse

将人脸添加到人脸列表 （V2）

操作 ID:

AddFaceToFaceListV2

将人脸添加到人脸列表。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
图像 URL	url		string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP
目标人脸	targetFace		string	一个人脸矩形，用于指定要添加到人员的目标人脸，格式为 targetFace=left、top、width、height
用户数据	userData		string	要出于任何目的添加的目标人脸的用户指定数据。 最大长度为 1KB。
人脸列表 ID	faceListId	True	string	有效字符为小写字母或数字或“-”或“_”，最大长度为 64。

返回

Body

AddPersonFaceResponse

检测人脸

操作 ID:

Detect

检测图像中的人脸并返回人脸位置，还可以选择使用 faceId、地标和属性。

参数

名称	密钥	必需	类型	说明
图像 URL	url	True	string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP

返回

物品

DetectResponse

检测人脸 （V2）

操作 ID:

DetectV2

检测图像中的人脸并返回人脸位置，还可以选择使用 faceId、地标和属性。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
图像 URL	url	True	string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP

返回

物品

DetectResponse

添加人脸

操作 ID:

AddPersonFace

向人员添加代表人脸进行标识。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	人员组
人员 ID	personId	True	string	将人脸添加到的目标人员。
图像 URL	url	True	string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP
目标人脸	targetFace		string	一个人脸矩形，用于指定要添加到人员的目标人脸，格式为 targetFace=left、top、width、height
用户数据	userData		string	要出于任何目的添加的目标人脸的用户指定数据。 最大长度为 1KB。

返回

Body

AddPersonFaceResponse

添加人脸 （V2）

操作 ID:

AddPersonFaceV2

向人员添加代表人脸进行标识。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	人员组
人员 ID	personId	True	string	将人脸添加到的目标人员。
图像 URL	url	True	string	图像必须是 JPEG、PNG、GIF（第一帧）或 BMP
目标人脸	targetFace		string	一个人脸矩形，用于指定要添加到人员的目标人脸，格式为 targetFace=left、top、width、height
用户数据	userData		string	要出于任何目的添加的目标人脸的用户指定数据。 最大长度为 1KB。

返回

Body

AddPersonFaceResponse

获取人员

操作 ID:

GetPerson

检索人员的信息，包括已注册的持久人脸、名称和 userData。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	指定包含目标人员的人员组。
人员 ID	personId	True	string	指定目标人员。

返回

Body

GetPersonResponse

获取人员组

操作 ID:

GetPersonGroup

检索人员组的信息，包括其名称和 userData。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	目标人员组 ID。

返回

Body

GetPersonGroupResponse

获取人员组 （V2）

操作 ID:

GetPersonGroupV2

检索人员组的信息，包括其名称和 userData。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	目标人员组 ID。

返回

Body

GetPersonGroupResponse

获取人员（V2）

操作 ID:

GetPersonV2

检索人员的信息，包括已注册的持久人脸、名称和 userData。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	指定包含目标人员的人员组。
人员 ID	personId	True	string	指定目标人员。

返回

Body

GetPersonResponse

获取人脸

操作 ID:

GetPersonFace

检索有关 persistedFaceId、personId 及其所属 personGroupId 指定的持久人脸的信息。

参数

名称	密钥	必需	类型	说明
人员组 ID	personGroupId	True	string	指定包含目标人员的人员组。
人员 ID	personId	True	string	指定人脸所属的目标人员。
持久化人脸 ID	persistedFaceId	True	string	目标持久化人脸的 persistedFaceId。

返回

Body

GetPersonFaceResponse

获取人脸 （V2）

操作 ID:

GetPersonFaceV2

检索有关 persistedFaceId、personId 及其所属 personGroupId 指定的持久人脸的信息。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人员组 ID	personGroupId	True	string	指定包含目标人员的人员组。
人员 ID	personId	True	string	指定人脸所属的目标人员。
持久化人脸 ID	persistedFaceId	True	string	目标持久化人脸的 persistedFaceId。

返回

Body

GetPersonFaceResponse

获取人脸列表

操作 ID:

GetFaceList

检索人脸列表的信息，包括 faceListId、name、userData 和人脸列表中的人脸。

参数

名称	密钥	必需	类型	说明
人脸列表 ID	faceListId	True	string	目标人脸列表的 faceListId。

返回

Body

GetFaceListResponse

获取人脸列表 （V2）

操作 ID:

GetFaceListV2

检索人脸列表的信息，包括 faceListId、name、userData 和人脸列表中的人脸。

参数

名称	密钥	必需	类型	说明
资源子域或区域	subdomain	True	string	Azure 子域或地理区域（例如 westus）
人脸列表 ID	faceListId	True	string	目标人脸列表的 faceListId。

返回

Body

GetFaceListResponse

定义

DetectResponse

名称	路径	类型	说明
人脸 ID	faceId	string	检测到的人脸的唯一 faceId。 将在检测调用后 24 小时过期。
Top	faceRectangle.top	integer	图像上人脸位置的矩形区域的参数。
Left	faceRectangle.left	integer	图像上人脸位置的矩形区域的参数。
宽度	faceRectangle.width	integer	图像上人脸位置的矩形区域的参数。
高度	faceRectangle.height	integer	图像上人脸位置的矩形区域的参数。
左学生 X	faceLandmarks.pupilLeft.x	float	左学生 X 坐标。
左学生 Y	faceLandmarks.pupilLeft.y	float	左学生 y 坐标。
右学生 X	faceLandmarks.pupilRight.x	float	右学生 X 坐标。
右学生 Y	faceLandmarks.pupilRight.y	float	右学生 y 坐标。
鼻子尖 X	faceLandmarks.noseTip.x	float	鼻尖的 x 坐标。
鼻尖 Y	faceLandmarks.noseTip.y	float	鼻尖的 y 坐标。
嘴左 X	faceLandmarks.mouthLeft.x	float	嘴左侧的 x 坐标。
嘴左 Y	faceLandmarks.mouthLeft.y	float	嘴左侧的 y 坐标。
口右 X	faceLandmarks.mouthRight.x	float	嘴右侧的 x 坐标。
嘴右 Y	faceLandmarks.mouthRight.y	float	嘴右侧的 y 坐标。
左外眉 X	faceLandmarks.eyebrowLeftOuter.x	float	左眉的外侧的 x 坐标。
左外眉毛 Y	faceLandmarks.eyebrowLeftOuter.y	float	左眉的外侧的 y 坐标。
内左 Eybrow X	faceLandmarks.eyebrowLeftInner.x	float	左眉心内侧的 x 坐标。
内左眉毛 Y	faceLandmarks.eyebrowLeftInner.y	float	左眉心内侧的 y 坐标。
左眼外侧 X	faceLandmarks.eyeLeftOuter.x	float	左眼外侧的 x 坐标。
左外眼 Y	faceLandmarks.eyeLeftOuter.y	float	左眼外侧的 y 坐标。
左眼 X 的顶部	faceLandmarks.eyeLeftTop.x	float	左眼顶部的 x 坐标。
左眼 Y 顶部	faceLandmarks.eyeLeftTop.y	float	左眼顶部的 y 坐标。
左眼 X 底部	faceLandmarks.eyeLeftBottom.x	float	左眼底部的 x 坐标。
左眼 Y 底部	faceLandmarks.eyeLeftBottom.y	float	左眼底部的 y 坐标。
内左眼 X	faceLandmarks.eyeLeftInner.x	float	左眼内侧的 x 坐标。
内左眼 Y	faceLandmarks.eyeLeftInner.y	float	左眼内侧的 y 坐标。
内右 Eybrow X	faceLandmarks.eyebrowRightInner.x	float	右眉心内侧的 x 坐标。
内右眉毛 Y	faceLandmarks.eyebrowRightInner.y	float	右眉心内侧的 y 坐标。
外右眉毛 X	faceLandmarks.eyebrowRightOuter.x	float	右眉的外侧的 x 坐标。
右外眉毛 Y	faceLandmarks.eyebrowRightOuter.y	float	右眉的外侧的 y 坐标。
内右眼 X	faceLandmarks.eyeRightInner.x	float	右眼内侧的 x 坐标。
内右眼 Y	faceLandmarks.eyeRightInner.y	float	右眼内侧的 y 坐标。
右眼 X 顶部	faceLandmarks.eyeRightTop.x	float	右眼顶部的 x 坐标。
右眼 Y 顶部	faceLandmarks.eyeRightTop.y	float	右眼顶部的 y 坐标。
右眼 X 底部	faceLandmarks.eyeRightBottom.x	float	右眼底部的 x 坐标。
右眼 Y 底部	faceLandmarks.eyeRightBottom.y	float	右眼底部的 y 坐标。
外侧右眼 X	faceLandmarks.eyeRightOuter.x	float	右眼外侧的 x 坐标。
外侧右眼 Y	faceLandmarks.eyeRightOuter.y	float	右眼外侧的 y 坐标。
左鼻子根 X	faceLandmarks.noseRootLeft.x	float	鼻子根的左侧的 x 坐标。
左鼻子根 Y	faceLandmarks.noseRootLeft.y	float	鼻根左侧的 y 坐标。
右鼻根 X	faceLandmarks.noseRootRight.x	float	鼻子根的右侧的 x 坐标。
右鼻子根 Y	faceLandmarks.noseRootRight.y	float	鼻子根的右侧的 y 坐标。
左鼻子祭坛的顶部 X	faceLandmarks.noseLeftAlarTop.x	float	左鼻祭坛顶部的 x 坐标。
左鼻子祭坛的顶部 Y	faceLandmarks.noseLeftAlarTop.y	float	左鼻祭坛顶部的 y 坐标。
右鼻子祭坛 X 的顶部	faceLandmarks.noseRightAlarTop.x	float	右鼻祭坛顶部的 x 坐标。
右鼻子祭坛的顶部 Y	faceLandmarks.noseRightAlarTop.y	float	右鼻祭坛顶部的 y 坐标。
左鼻子祭坛的提示 X	faceLandmarks.noseLeftAlarOutTip.x	float	左鼻祭坛尖的 x 坐标。
左鼻子祭坛的尖出 Y	faceLandmarks.noseLeftAlarOutTip.y	float	左鼻祭坛尖尖的 y 坐标/
右鼻子祭坛的提示 X	faceLandmarks.noseRightAlarOutTip.x	float	右鼻祭坛尖的 x 坐标。
右鼻子祭坛的尖出 Y	faceLandmarks.noseRightAlarOutTip.y	float	右鼻祭坛尖尖的 y 坐标。
上唇 X 顶部	faceLandmarks.upperLipTop.x	float	上唇顶部的 x 坐标。
上唇 Y 顶部	faceLandmarks.upperLipTop.y	float	上唇顶部的 y 坐标。
上唇 X 底部	faceLandmarks.upperLipBottom.x	float	上唇底部的 x 坐标。
上唇 Y 底部	faceLandmarks.upperLipBottom.y	float	上唇底部的 y 坐标。
下唇 X 顶部	faceLandmarks.underLipTop.x	float	下唇顶部的 x 坐标。
下唇 Y 顶部	faceLandmarks.underLipTop.y	float	嘴唇下顶部的 y 坐标。
下唇 X 底部	faceLandmarks.underLipBottom.x	float	下唇底部的 x 坐标。
下唇 Y 底部	faceLandmarks.underLipBottom.y	float	下唇底部的 y 坐标。
头部姿势音调	faceAttributes.headPose.pitch	float	保留字段，始终返回 0。
头姿势卷	faceAttributes.headPose.roll	float	头部姿势的卷。
头部姿势偏航	faceAttributes.headPose.yaw	float	头部的偏航姿势。
眼镜	faceAttributes.glasses	string	眼镜的类型。

AddPersonFaceResponse

名称	路径	类型	说明
持久化人脸 ID	persistedFaceId	string

GetPersonGroupResponse

名称	路径	类型	说明
人员组 ID	personGroupId	string
Name	name	string
用户数据	userData	string

GetFaceListResponse

名称	路径	类型	说明
持久化人脸	persistedFaces	array of object
持久化人脸 ID	persistedFaces.persistedFaceId	string	人脸的 ID。
用户数据	persistedFaces.userData	string	附加到每个人脸的用户提供的数据。
人脸列表 ID	faceListId	string	目标人脸列表的 faceListId。
Name	name	string	人脸列表的显示名称。
用户数据	userData	string	附加到人脸列表的用户提供的数据。

GetPersonFaceResponse

名称	路径	类型	说明
持久化人脸 ID	persistedFaceId	string
用户数据	userData	string

CreatePersonResponse

名称	路径	类型	说明
人员 ID	personId	string

GetPersonResponse

名称	路径	类型	说明
人员 ID	personId	string
持久化人脸 ID	persistedFaceIds	array of object
持久化人脸 ID	persistedFaceIds.persistedFaceId	string
Name	name	string
用户数据	userData	string

VerifyResponse

名称	路径	类型	说明
相同	isIdentical	boolean	如果两张脸属于同一个人或人脸属于该人，则为 true，否则为 false。
置信度	confidence	float	数字表示两张人脸是否属于同一个人，或者人脸是否属于该人的相似性置信度。