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 arquivos de log para descoberta na nuvem
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:

Recurso	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/
Ficheiros	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

Nota

Nem todos os operadores são compatíveis com todos os filtros.

A tabela a seguir descreve os operadores suportados:

Operador	Tipo de resposta	Description
contém	Lista de cadeias de caracteres	Retorna todos os registros relevantes que contêm uma das cadeias de caracteres fornecidas
deq	Lista de valores	Retorna todos os registros que contêm um valor que não é igual a um dos valores fornecidos
descendente de	Lista de valores	Devolve todos os registos relevantes que correspondam a valores ou descendentes dos mesmos
doesnotstartcom	Lista de cadeias de caracteres	Retorna todos os registros relevantes que não começam com cada uma das cadeias de caracteres fornecidas
endswith	Lista de cadeias de caracteres	Retorna todos os registros relevantes que terminam com uma das cadeias de caracteres fornecidas
eq	Lista de valores	Devolve todos os registos relevantes que contenham um dos valores fornecidos
gt	valor único	Devolve todos os registos cujo valor é superior ao valor fornecido
gte	valor único	Devolve todos os registos cujo valor é superior ou igual ao valor fornecido
gte_ndays	Número	Devolve todos os registos com data posterior a N dias atrás
isnotset	boolean	Quando definido como "true", retorna todos os registros relevantes que não têm um valor no campo especificado
ISSET	boolean	Quando definido como "true", retorna todos os registros relevantes que têm um valor no campo especificado
lt	valor único	Devolve todos os registos cujo valor é inferior ao valor fornecido
lte	valor único	Devolve todos os registos cujo valor é inferior ou igual ao valor fornecido
lte_ndays	Número	Devolve todos os registos com data anterior a N dias atrás
Ncontém	Lista de cadeias de caracteres	Retorna todos os registros relevantes que não contêm uma das cadeias de caracteres fornecidas
ndescendente de	Lista de valores	Devolve todos os registos relevantes que não correspondem a valores ou descendentes dos mesmos
NEQ	Lista de valores	Devolve todos os registos relevantes que não contenham todos os valores fornecidos
range	Lista de objetos contendo campos "start" e "end"	Devolve todos os registos dentro de um dos intervalos fornecidos
startswith	Lista de cadeias de caracteres	Retorna todos os registros relevantes começando com uma das cadeias de caracteres fornecidas
começa comsingle	string	Retorna todos os registros relevantes começando com a cadeia de caracteres fornecida
texto	string	Executa uma pesquisa de texto completo de todos os registros

Próximos passos

Autenticação de API

Se tiver algum problema, estamos aqui para ajudar. Para obter assistência ou suporte para o problema do seu produto, abra um ticket de suporte.

Partilhar via