Defender for Cloud Apps REST API

Artigo
01/23/2024

Este artigo descreve como interagir com o Defender for Cloud Apps por HTTPS.

A API do Microsoft Defender for Cloud Apps fornece acesso programático ao Defender for Cloud Apps por meio de pontos de extremidade da API REST. Os aplicativos podem usar a API para executar operações de leitura e atualização em dados e objetos do Defender for Cloud Apps. Por exemplo, a API do Defender for Cloud Apps suporta as seguintes operações comuns para um objeto de usuário:

Carregar ficheiros de registo para o Cloud Discovery
Gerar scripts de bloco
Listar atividades e alertas
Ignorar ou resolver alertas

Estrutura da URL da API

Para usar a API do Defender for Cloud Apps, 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 for Cloud Apps para seu locatário, execute as seguintes etapas:

No Portal do Microsoft Defender, selecione Configurações. Em seguida, escolha Cloud Apps. Em Sistema, selecione Sobre.
Na tela Defender for Cloud Apps 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 o URL do seu portal for https://mytenant.us2.contoso.com, o URL da API será https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokens de API

O Defender for Cloud Apps requer um token de API no cabeçalho de todas as solicitações de API para o servidor, como as seguintes:

Authorization: Token <your_token_key>

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

Para obter mais informaçõ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"

Quais são as ações suportadas?

A tabela a seguir descreve as ações suportadas:

Resource	Verbos HTTP	Rotas URI
Atividades	GET ou POST	/api/v1/atividades/
Alertas	GET ou POST	/api/v1/alertas/
Enriquecimento de dados	OBTER, PUBLICAR ou EXCLUIR	/api/sub-rede/
Entidades	GET ou POST	/api/v1/entidades/
Files	GET ou POST	/api/v1/arquivos/

Onde Recurso representa um grupo de entidades relacionadas.

Que tipos de campo são suportados?

A tabela a seguir descreve os tipos de campo suportados:

Campo	Descrição
string	Uma cadeia de caracteres textual
boolean	Um valor booleano que representa true/false
integer	Inteiro assinado de 32 bits
carimbo de data/hora	Milésimos de segundo desde a época

Carimbos de Data/Hora

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

Limites

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

Os seguintes métodos são suportados para fornecer o parâmetro limit:

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

Nota

Se nenhum limite for fornecido, um padrão de 100 será definido.
As respostas para todas as solicitações feitas com o token da 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 grande número de resultados, será ú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 suportam 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 suporta vários valores para fornecer consultas poderosas. Ao combinar filtros e operadores, usamos E 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