Person Directories - List Faces

Serviço:

Azure AI Services

Versão da API:

2025-05-01-preview

Listar rostos.

GET {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces?api-version=2025-05-01-preview

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
endpoint	path	True	string (uri)	Ponto de extremidade de serviço de Compreensão de Conteúdo.
personDirectoryId	path	True	string pattern: ^[a-zA-Z0-9._-]{1,64}$	O identificador exclusivo do diretório de pessoas.
api-version	query	True	string minLength: 1	A versão da API a ser usada para esta operação.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
x-ms-client-request-id		string (uuid)	Um identificador de cadeia de caracteres opaco, globalmente exclusivo e gerado pelo cliente para a solicitação.

Respostas

Nome	Tipo	Description
200 OK	PagedPersonDirectoryFace	A solicitação foi bem-sucedida. Cabeçalhos x-ms-client-request-id: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

Tipo: apiKey
Em: header

OAuth2Auth

Tipo: oauth2
Flow: accessCode
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize
URL do Token: https://login.microsoftonline.com/common/oauth2/token

Escopos

Nome	Description
https://cognitiveservices.azure.com/.default

Exemplos

List Faces in Person Directory

Solicitação de exemplo

HTTP

GET {endpoint}/contentunderstanding/personDirectories/myDirectory/faces?api-version=2025-05-01-preview

Resposta de exemplo

Código de status:

200

{
  "value": [
    {
      "faceId": "7a87f162-8dd5-4aea-8810-373e36b96b38",
      "personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
      "boundingBox": {
        "left": 33,
        "top": 73,
        "width": 262,
        "height": 324
      },
      "imageReferenceId": "face1.jpg"
    },
    {
      "faceId": "f28b3cda-4005-44b6-8518-6fcddef108cb",
      "personId": "19323b77-2012-487b-b131-09c318dc23df",
      "boundingBox": {
        "left": 87,
        "top": 96,
        "width": 235,
        "height": 345
      },
      "imageReferenceId": "face2.jpg"
    }
  ],
  "nextLink": "https://myendpoint.cognitiveservices.azure.com/contentunderstanding/personDirectories/myDirectory/faces?nextLink=nextLinkData&api-version=2025-05-01-preview"
}

Definições

Nome	Description
Azure.Core.Foundations.Error	O objeto de erro.
Azure.Core.Foundations.ErrorResponse	Uma resposta que contém detalhes do erro.
Azure.Core.Foundations.InnerError	Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da API do Microsoft One - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.
BoundingBox	Caixa delimitadora em uma imagem.
PagedPersonDirectoryFace	Coleção paginada de itens PersonDirectoryFace
PersonDirectoryFace	Face em um diretório de pessoas.

Azure.Core.Foundations.Error

Objeto

O objeto de erro.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
details	Azure.Core.Foundations.Error[]	Uma matriz de detalhes sobre erros específicos que levaram a esse erro relatado.
innererror	Azure.Core.Foundations.InnerError	Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.
message	string	Uma representação do erro em formato legível por humanos.
target	string	O destino do erro.

Azure.Core.Foundations.ErrorResponse

Objeto

Uma resposta que contém detalhes do erro.

Nome	Tipo	Description
error	Azure.Core.Foundations.Error	O objeto de erro.

Azure.Core.Foundations.InnerError

Objeto

Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da API do Microsoft One - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
innererror	Azure.Core.Foundations.InnerError	Erro interno.

BoundingBox

Objeto

Caixa delimitadora em uma imagem.

Nome	Tipo	Description
height	integer (int32)	Altura da caixa delimitadora.
left	integer (int32)	Coordenada esquerda da caixa delimitadora.
top	integer (int32)	Coordenada superior da caixa delimitadora.
width	integer (int32)	Largura da caixa delimitadora.

PagedPersonDirectoryFace

Objeto

Coleção paginada de itens PersonDirectoryFace

Nome	Tipo	Description
nextLink	string (uri)	O link para a próxima página de itens
value	PersonDirectoryFace[]	Os itens PersonDirectoryFace nesta página

PersonDirectoryFace

Objeto

Face em um diretório de pessoas.

Nome	Tipo	Description
boundingBox	BoundingBox	Caixa delimitadora da face na imagem de origem.
faceId	string pattern: ^[a-zA-Z0-9._-]{1,64}$	O identificador exclusivo do rosto.
imageReferenceId	string	Identificador fornecido pelo usuário para a imagem de origem.
personId	string	Pessoa associada ao rosto, se houver.