Endpoints reference: Microsoft Entra SDK for Agent ID HTTP API

Este documento fornece referência completa para os endpoints HTTP expostos pelo Microsoft Entra SDK para o AgentID.

Especificação API

OpenAPI: Disponível em (ambiente de desenvolvimento) e no repositório:

Utilize-o para:

• Gerar código de cliente
• Validar pedidos
• Descubra os endpoints disponíveis

Visão geral do endpoint

Authentication

Todos os pontos finais de aquisição e validação de token exigem um token de portador no cabeçalho, a Authorization menos que explicitamente marcado como não autenticado:

GET /AuthorizationHeader/Graph
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Os tokens são validados contra as definições configuradas do Microsoft Entra ID (inquilino, público, emissor, escopos se ativados).

/Validate

Valida o token de portador de entrada e retorna suas declarações.

Solicitação

GET /Validate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Resposta bem-sucedida (200)

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "claims": {
    "aud": "api://your-api-id",
    "iss": "https://sts.windows.net/tenant-id/",
    "iat": 1234567890,
    "nbf": 1234567890,
    "exp": 1234571490,
    "acr": "1",
    "appid": "client-id",
    "appidacr": "1",
    "idp": "https://sts.windows.net/tenant-id/",
    "oid": "user-object-id",
    "tid": "tenant-id",
    "scp": "access_as_user",
    "sub": "subject",
    "ver": "1.0"
  }
}

Exemplos de erros

// 400 Bad Request - No token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "No token found"
}

// 401 Unauthorized - Invalid token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Unauthorized",
  "status": 401
}

/AuthorizationHeader/{serviceName}

Adquire um token de acesso para a API downstream configurada e o retorna como um valor de cabeçalho de autorização. Se um token de portador de usuário é fornecido de entrada, OBO (delegado) é usado; caso contrário, os padrões de contexto do aplicativo serão aplicados (se habilitados).

Parâmetro de caminho

• serviceName – Nome da API downstream na configuração

Parâmetros de consulta

Sobreposições padrão

Identidade do agente

Regras:

• AgentUsername ou AgentUserId exigir AgentIdentity (agente do usuário).
• AgentUsername e AgentUserId excluem-se mutuamente.
• AgentIdentity sozinho = agente autônomo.
• AgentIdentity + token de entrada do usuário = agente delegado.

Examples

Pedido básico:

GET /AuthorizationHeader/Graph HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Resposta

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Resposta PoP/SHR:

{
  "authorizationHeader": "PoP eyJ0eXAiOiJhdCtqd3QiLCJhbGc..."
}

/AuthorizationHeaderUnauthenticated/{serviceName}

O mesmo comportamento e parâmetros que /AuthorizationHeader/{serviceName} mas nenhum token de usuário de entrada é esperado. Usado para aquisição de identidade somente de aplicativo ou autônoma/agente sem um contexto de usuário. Evita a sobrecarga de validar um token de usuário.

Solicitação

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Resposta

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

/DownstreamApi/{serviceName}

Adquire um token de acesso e executa uma solicitação HTTP para a API downstream. Retorna o código de status, cabeçalhos e corpo da resposta downstream. Suporta padrões de identidade de OBO, somente aplicativo ou agente.

Parâmetro de caminho

• serviceName – Nome da API downstream configurado.

Parâmetros adicionais de consulta (além dos /AuthorizationHeader parâmetros)

Encaminhamento corporal do pedido

O corpo é passado inalterado:

POST /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{ 
  "subject": "Hello", 
   "body": { "contentType": "Text", "content": "Hello world" } 
}

Resposta

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "content": "{\"@odata.context\":\"...\",\"displayName\":\"...\"}"
}

Espelho de erros /AuthorizationHeader mais códigos de status de erro de API downstream.

/DownstreamApiUnauthenticated/{serviceName}

O mesmo que /DownstreamApi/{serviceName} , mas nenhum token de usuário de entrada é validado. Use para operações somente de aplicativo ou agente autônomo.

/saúdez

Ponto de avaliação da sonda de saúde básica.

Resposta

Saudável (200):

HTTP/1.1 200 OK

Insalubridade (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Retorna a especificação OpenAPI 3.0 (somente ambiente de desenvolvimento). Use para:

• Gerar código de cliente
• Validar pedidos
• Descubra os endpoints

Padrões de erro comuns

Pedido negativo (400)

Nome do serviço em falta:

// 400 Bad Request - Missing service name
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "Service name is required" }

// 400 Bad Request - Invalid agent combination
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "AgentUsername and AgentUserId are mutually exclusive" }

// 401 Unauthorized - Invalid token
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Unauthorized", "status": 401 }

// 403 Forbidden - Missing scope
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden", "status": 403, "detail": "The scope 'access_as_user' is required" }

// 404 Not Found - Service not configured
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Downstream API 'UnknownService' not configured" }

// 500 Internal Server Error - Token acquisition failure
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "Failed to acquire token for downstream API" }

Exemplo de erro MSAL

{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "MSAL.NetCore.invalid_grant: AADSTS50076: Due to a configuration change ...", "extensions": { "errorCode": "invalid_grant", "correlationId": "..." } }

Referência completa de sobreposição

optionsOverride.Scopes=<scope>     # Repeatable
optionsOverride.RequestAppToken=<true|false>
optionsOverride.BaseUrl=<url>
optionsOverride.RelativePath=<path>
optionsOverride.HttpMethod=<method>
optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>
optionsOverride.AcquireTokenOptions.AuthenticationScheme=<scheme>
optionsOverride.AcquireTokenOptions.CorrelationId=<guid>
optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>
optionsOverride.AcquireTokenOptions.PopClaims=<json>
optionsOverride.CustomHeader.<Name>=<value>

AgentIdentity=<agent-client-id>
AgentUsername=<user-upn>            # Requires AgentIdentity
AgentUserId=<user-object-id>        # Requires AgentIdentity

Exemplos de substituição

Substituir escopos:

GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Limitação de Velocidade

O próprio Microsoft Entra SDK para o Agent ID não impõe limites de taxa. Os limites efetivos provêm de:

1. Microsoft Entra ID token throttling (não deveria acontecer, pois o SDK armazena o token em cache)
2. Limites da API a jusante
3. Eficiência do cache de tokens (reduz o volume de aquisição)

Melhores práticas

1. Prefira a configuração às substituições ad-hoc.
2. Mantenha os nomes de serviço estáticos e declarativos.
3. Implementar políticas de repetição para falhas transitórias (HTTP 500/503).
4. Valide os parâmetros do agente antes de chamar.
5. Registre IDs de correlação para rastreamento entre serviços.
6. Monitore a latência de aquisição de tokens e as taxas de erro.
7. Use sondas de integridade em plataformas de orquestração.

Conteúdo relacionado

• Referência de configuração
• Identidades do agente
• Validar cabeçalho de autorização
• Chamar API a jusante