API REST Defender for Cloud Apps

Artigo
11/28/2024

Este artigo descreve como interagir com Defender for Cloud Apps através de HTTPS.

A API de Microsoft Defender for Cloud Apps fornece acesso programático a Defender for Cloud Apps 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 for Cloud Apps dados e objetos. Por exemplo, a API de Defender for Cloud Apps 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 resolver alertas

Estrutura do URL da API

Para utilizar a API de Defender for Cloud Apps, 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 for Cloud Apps 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.
No Defender for Cloud Apps 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 for Cloud Apps 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/
Ficheiros	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
cadeia	Uma cadeia de carateres textuais
booleano	Um valor booleano que representa true/false
número inteiro	Número inteiro assinado de 32 bits
Carimbo de data/hora	Milissegundos desde época

Carimbos de data/hora

As menções aos carimbos de data/hora na API de Defender for Cloud Apps 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 do formulário
Corpo JSON (com Content-Type: multipart/form-data e um cabeçalho de limite adequado)

Nota

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.

Estrutura

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

Nota

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
contém	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
terminacom	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	número	Devolve todos os registos com data posterior a N dias atrás
isnotset	booleano	Quando definido como "verdadeiro", devolve todos os registos relevantes que não têm um valor no campo especificado
isset	booleano	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	número	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
começacom	lista de cadeias	Devolve todos os registos relevantes a partir de uma das cadeias fornecidas
startswithsingle	cadeia	Devolve todos os registos relevantes a partir da cadeia fornecida
Texto	cadeia	Efetua uma pesquisa em texto completo de todos os registos

Passos seguintes

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.

Partilhar via