Cloud App Security REPOUSO API

Aplica-se a: Microsoft Cloud App Security

Importante

Os nomes dos produtos de proteção contra ameaças da Microsoft estão a mudar. Leia mais sobre esta e outras atualizações aqui. Vamos atualizar nomes em produtos e nos documentos num futuro próximo.

Este artigo descreve como interagir com Cloud App Security sobre HTTPS.

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

  • Faça upload de ficheiros de registo para Cloud Discovery
  • Gerar scripts de blocos
  • Listar atividades e alertas
  • Dispensar ou resolver alertas

Estrutura do URL da API

Para utilizar a API Cloud App Security, você deve primeiro obter o URL da API do seu inquilino. O URL API utiliza o seguinte formato: https://<portal_url>/api/<endpoint> .

Para obter o URL do portal Cloud App Security para o seu inquilino, faça os seguintes passos:

  1. No portal Cloud App Securityclique no ícone do ponto de interrogação na barra de menu. Em seguida, selecione About.

    clique em cerca de.

  2. Na Cloud App Security sobre o ecrã, pode ver o url do portal.

    Veja o seu centro de dados.

Assim que tiver o url do portal, /api adicione-lhe o sufixo para obter o URL da API. Por exemplo, se o URL do seu portal https://mytenant.us2.contoso.com for, então o URL da API é https://mytenant.us2.contoso.com/api .

Tokens de API

Cloud App Security requer um token API no cabeçalho de todos os pedidos da API para o servidor, tais como o seguinte:

Authorization: Token <your_token_key>

Onde <your_token_key> está o seu símbolo pessoal da API.

Para obter mais informações sobre fichas da API, consulte tokens da API de gestão.

Exemplo

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

Quais são as ações suportadas?

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

Recurso Verbos HTTP Rotas URI
Atividades GET ou POST /api/v1/atividades/
Alertas GET ou POST /api/v1/alertas/
Cloud Discovery GET, POST, OU PUT /api/v1/discovery/
Melhoramento de Dados GET, POST OU DELETE /api/subnet/
Entidades GET ou POST /api/v1/entidades/
Ficheiros GET ou POST /api/v1/ficheiros/

Onde o 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 Description
cadeia (de carateres) Uma corda textual
boolean Um valor booleano que representa verdadeiro/falso
número inteiro Inteiro assinado de 32 bits
carimbo de data/hora Milissegundos desde época

Carimbos de Data/Hora

Menções de timetamps no Cloud App Security API referem-se à contraompia tempotária Unix em milissegundos. Esta estampização de tempo é determinada pelo número de milissegundos desde 1970-01-01 0:00:00. Pode utilizar o cmdlet PowerShell para converter datas em timetamps.

Limites

Pode optar por limitar os seus pedidos fornecendo um parâmetro limite no pedido.

São apoiados os seguintes métodos para fornecer o parâmetro-limite:

  • URL codificado (com Content-Type: application/x-www-form-urlencoded cabeçalho)
  • Formulários de dados
  • Corpo JSON (com Content-Type: multipart/form-data e um cabeçalho de fronteira apropriado)

Nota

  • Se não for fixado um limite de 100, será definido um predefinido de 100.
  • As respostas para todos os pedidos feitos com o token da API estão limitadas a um máximo de 100 itens.
  • O limite de aceleração para todos os pedidos da API é de 30 pedidos por minuto por inquilino.

Filtros

Quando tiver um grande número de resultados, encontrará útil para afinar pedidos usando filtros. Esta secção descreve a estrutura de filtros e operadores que podem ser utilizados com filtros.

Estrutura

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

A maioria dos filtros suporta vários valores para lhe fornecer consultas poderosas. Ao combinar filtros e operadores utilizamos e como operador lógico entre os filtros.

Exemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.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 apoiados:

Operador Tipo de resposta Description
contains lista de cordas Devolve todos os registos relevantes que contenham uma das cordas fornecidas
deq lista de valores Devolve todos os registos que contêm um valor que não é igual a um dos valores fornecidos
descendentes de lista de valores Devolve todos os registos relevantes correspondentes a valores ou descendentes dos mesmos
não começou com lista de cordas Devolve todos os registos relevantes não começando com cada uma das cordas fornecidas
termina com lista de cordas Devolve todos os registos relevantes que terminam com uma das cordas 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 seja superior ao valor fornecido
gte valor único Devolve todos os registos cujo valor seja superior ou igual ao valor fornecido
gte_ndays número Devolve todos os registos com data mais tarde do que há dias
isnotset boolean Quando definido como "verdadeiro", devolve todos os registos relevantes que não têm um valor no campo especificado
isset boolean 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 seja inferior ao valor fornecido
Rio Ite valor único Devolve todos os registos cujo valor seja inferior ou igual ao valor fornecido
lte_ndays número Devolve todos os registos com data mais cedo do que há dias
ncontains lista de cordas Devolve todos os registos relevantes que não contenham uma das cordas fornecidas
ndescendantof lista de valores Devolve todos os registos relevantes que não correspondam a valores ou descendentes dos mesmos
neq lista de valores Devolve todos os registos relevantes que não contenham todos os valores fornecidos
gama lista de objetos que contêm campos "iniciar" e "terminar" Devolve todos os registos dentro de uma das gamas fornecidas
começa com lista de cordas Devolve todos os registos relevantes a partir de uma das cordas fornecidas
começa com o comsingle string Devolve todos os registos relevantes a partir da cadeia fornecida
texto string Realiza uma pesquisa por texto completo de todos os registos

Passos seguintes

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