API REST do Defender para Aplicativos de Nuvem

Artigo
01/23/2024

Este artigo descreve como interagir com o Defender para Aplicativos de Nuvem por HTTPS.

A API do Microsoft Defender para Aplicativos de Nuvem fornece acesso programático ao Defender para Aplicativos de Nuvem por meio de pontos de extremidade da API REST. Aplicativos podem usar a API para realizar operações de leitura e atualização nos dados e objetos do Defender para Aplicativos de Nuvem. Por exemplo, a API do Defender para Aplicativos de Nuvem oferece suporte às seguintes operações comuns para um objeto de usuário:

Carregar arquivos de log para o Cloud Discovery
Gerar scripts de bloqueio
Listar atividades e alertas
Descartar ou resolver alertas

Estrutura de URL da API

Para usar a API do Defender para Aplicativos de Nuvem, você deve primeiro obter a URL da API do seu locatário. O URL da API usa o seguinte formato: https://<portal_url>/api/<endpoint>.

Para obter a URL da API do Defender para Aplicativos de Nuvem para seu locatário, execute as seguintes etapas:

No portal do Microsoft Defender, selecione Configurações. Em seguida, escolha Aplicativos de Nuvem. Em Sistema, selecione Sobre.
Na tela Defender para Aplicativos de Nuvem sobre, você pode ver a URL da API.

Depois de ter a URL da API, adicione o sufixo /api a ela para obter a URL da API. Por exemplo, se a URL do seu portal for https://mytenant.us2.contoso.com, a URL da API será https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokens de API

O Defender para Aplicativos de Nuvem requer um token de API no cabeçalho de todas as solicitações de API para o servidor, como o seguinte:

Authorization: Token <your_token_key>

Onde <your_token_key> está seu token de API pessoal.

Para obter mais inmaneirações sobre tokens de API, consulte Gerenciando tokens de API.

Tokens de API - exemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

Há suporte para quais ações?

A tabela a seguir descreve as ações com suporte:

Recurso	Verbos HTTP	Rotas de URI
Atividades	GET ou POST	/api/v1/activities/
Alertas	GET ou POST	/api/v1/alerts/
Enriquecimento de dados	GET, POST ou DELETE	/api/subnet/
Entidades	GET ou POST	/api/v1/entities/
Arquivos	GET ou POST	/api/v1/files/

Onde Resource representa um grupo de entidades relacionadas.

Quais tipos de campo são suportados?

A tabela a seguir descreve os operadores de campos compatíveis:

Campo	Descrição
string	Uma cadeia de caracteres textual
boolean	Um valor booliano que representa true/false
Número inteiro	Inteiro com sinal de 32 bits
timestamp	Milésimos de segundos desde a época

Carimbos de data/hora

Menções de carimbos de data/hora na API do Defender para Aplicativos de Nuvem referem-se ao carimbo de data/hora do Unix em milissegundos. Esse carimbo de data/hora é determinado pelo número de milissegundos desde 1970-01-01 0:00:00. Você pode utilizar o cmdlet get-date do PowerShell para converter datas em carimbos de data/hora.

Limites

Você pode optar por limitar suas solicitações fornecendo um parâmetro de limite na solicitação.

Os seguintes métodos têm suporte para fornecer o parâmetro de limite:

Codificado por URL (com Content-Type: application/x-www-form-urlencoded cabeçalho)
Dados de formulário
Corpo JSON (com Content-Type: multipart/form-data e um cabeçalho de limite apropriado)

Observação

Se nenhum limite for fornecido, um padrão de 100 será definido.
As respostas para todas as solicitações feitas com o token de API são limitadas a um máximo de 100 itens.
O limite de aceleração para todas as solicitações de API é de 30 solicitações por minuto por locatário.

Filtros

Quando você tiver um número grande de resultados, achará útil ajustar as solicitações usando filtros. Esta seção descreve a estrutura e os operadores que podem ser usados com filtros.

Estrutura

Alguns de nossos endpoints de API oferecem suporte a filtros ao executar consultas. Em suas seções relevantes, você encontrará uma referência listando todos os campos filtráveis disponíveis e operadores suportados para esse recurso.

A maioria dos filtros oferece suporte a vários valores para fornecer consultas poderosas. Ao combinar filtros e operadores, usamos AND como o operador lógico entre os filtros.

Filtros - exemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

Operadores