API REST do Defender para Aplicativos na Nuvem

Artigo
11/28/2024

Este artigo descreve como interagir com Defender para Aplicativos de Nuvem através de HTTPS.

A API de Microsoft Defender para Aplicativos de Nuvem fornece acesso programático a Defender para Aplicativos de Nuvem através de pontos finais da API REST. As aplicações podem utilizar a API para realizar operações de leitura e atualização em Defender para Aplicativos de Nuvem dados e objetos. Por exemplo, a API de Defender para Aplicativos de Nuvem suporta as seguintes operações comuns para um objeto de utilizador:

Carregar ficheiros de registo para a deteção da cloud
Gerar scripts de blocos
Listar atividades e alertas
Dispensar ou resolve alertas

Estrutura do URL da API

Para utilizar a API de Defender para Aplicativos de Nuvem, primeiro tem de obter o URL da API a partir do seu inquilino. O URL da API utiliza o seguinte formato: https://<portal_url>/api/<endpoint>.

Para obter o URL da API Defender para Aplicativos de Nuvem para o seu inquilino, siga os seguintes passos:

No Portal do Microsoft Defender, selecione Definições. Em seguida, selecione Aplicações na Cloud. Em Sistema, selecione Acerca de.
Na Defender para Aplicativos de Nuvem sobre o ecrã, pode ver o URL da API.

Assim que tiver o URL da API, adicione-lhe o /api sufixo para obter o URL da API. Por exemplo, se o URL do portal for https://mytenant.us2.contoso.com, o URL da API será https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokens de API

Defender para Aplicativos de Nuvem requer um token de API no cabeçalho de todos os pedidos de API para o servidor, como o seguinte:

Authorization: Token <your_token_key>

Onde <your_token_key> está o token pessoal da API.

Para obter mais informações sobre tokens de API, veja Managing API tokens (Gerir 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"

Que ações são suportadas?

A tabela seguinte descreve as ações suportadas:

Recurso	Verbos HTTP	Rotas URI
Atividades	GET ou POST	/api/v1/activities/
Alertas	GET ou POST	/api/v1/alerts/
Melhoramento de Dados	GET, POST ou DELETE	/api/sub-rede/
Entidades	GET ou POST	/api/v1/entities/
Arquivos	GET ou POST	/api/v1/files/

Em que Recurso representa um grupo de entidades relacionadas.

Que tipos de campo são suportados?

A tabela seguinte descreve os tipos de campo suportados:

Campo	Descrição
string	Uma cadeia de carateres textuais
booliano	Um valor booleano que representa true/false
inteiro	Inteiro assinado de 32 bits
Carimbo de data/hora	Milissegundos desde época

Carimbos de data/hora

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

Limites

Pode optar por limitar os pedidos ao fornecer um parâmetro de limite no pedido.

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

Codificado com 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 adequado)

Observação

Se não for fornecido nenhum limite, será definida uma predefinição de 100.
As respostas para todos os pedidos feitos com o token de API estão limitadas a um máximo de 100 itens.
O limite de limitação para todos os pedidos de API é de 30 pedidos por minuto por inquilino.

Filtros

Quando tiver um grande número de resultados, será útil ajustar os pedidos através de filtros. Esta secção descreve a estrutura de e os operadores que podem ser utilizados com filtros.

Structure

Alguns dos nossos pontos finais de API suportam filtros ao executar consultas. Nas respetivas secções relevantes, encontrará uma referência que lista todos os campos filtráveis disponíveis e operadores suportados para esse recurso.

A maioria dos filtros suporta vários valores para lhe fornecer consultas poderosas. Ao combinar filtros e operadores, utilizamos 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

Observação

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

A tabela seguinte descreve os operadores suportados:

Operador	Tipo de resposta	Descrição
contains	lista de cadeias	Devolve todos os registos relevantes que contêm uma das cadeias fornecidas
deq	lista de valores	Devolve todos os registos que contêm um valor que não é igual a um dos valores fornecidos
descendente de	lista de valores	Devolve todos os registos relevantes correspondentes a valores ou descendentes dos mesmos
doesnotstartwith	lista de cadeias	Devolve todos os registos relevantes que não começam com cada uma das cadeias fornecidas
endswith	lista de cadeias	Devolve todos os registos relevantes que terminam com uma das cadeias fornecidas
eq	lista de valores	Devolve todos os registos relevantes que contêm um dos valores fornecidos
gt	valor único	Devolve todos os registos cujo valor é maior do que o valor fornecido
gte	valor único	Devolve todos os registos cujo valor é maior ou igual ao valor fornecido
gte_ndays	number	Devolve todos os registos com data posterior a N dias atrás
isnotset	booliano	Quando definido como "verdadeiro", devolve todos os registos relevantes que não têm um valor no campo especificado
isset	booliano	Quando definido como "verdadeiro", devolve todos os registos 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 é menor ou igual ao valor fornecido
lte_ndays	number	Devolve todos os registos com data anterior a N dias atrás
ncontains	lista de cadeias	Devolve todos os registos relevantes que não contêm uma das cadeias fornecidas
ndescendantof	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 contêm todos os valores fornecidos
intervalo	lista de objetos que contêm campos "iniciar" e "terminar"	Devolve todos os registos dentro de um dos intervalos fornecidos
startswith	lista de cadeias	Devolve todos os registos relevantes a partir de uma das cadeias fornecidas
startswithsingle	string	Devolve todos os registos relevantes a partir da cadeia fornecida
texto	cadeia de caracteres	Efetua uma pesquisa em texto completo de todos os registos

Próximas etapas

Autenticação de API

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

Compartilhar via