IBM MaaS360 API de referência para serviços da Web

IBM® MaaS360® oferece um conjunto robusto de serviços web RESTful que permite que administradores e desenvolvedores interajam programaticamente com a plataforma para gerenciar dispositivos, aplicativos, usuários e muito mais. O conteúdo a seguir explica como acessar a documentação da API, autenticar seu aplicativo e realizar chamadas reais à API por meio de exemplos práticos.

A referência da API para serviços da web inclui informações como notas de implementação, atributos obrigatórios para a execução da API, detalhes sobre controle de acesso, classes de resposta com exemplos de modelos e detalhes sobre parâmetros.

Acessando a documentação da API no portal IBM MaaS360

Os administradores devem ter o Web Services Função para visualizar e interagir com a documentação dos Serviços Web e gerenciar chaves de acesso diretamente no Portal IBM MaaS360.

O uso da API segue os mesmos controles de acesso baseados em funções que o acesso padrão ao portal. Certifique-se de que a conta de serviço da API tenha as funções adequadas atribuídas para realizar as tarefas necessárias. Para obter mais informações, consulte Funções e direitos de acesso para administradores do portal IBM MaaS360.

Como acessar a documentação

Siga os passos para acessar a documentação da API de Serviços Web no Portal IBM MaaS360.
  1. Na página inicial do Portal IBM MaaS360, clique em Configuração > API de Serviços Web > Documentação.
    Importante: Ao realizar testes na documentação, você deve usar sua conta ou a mesma conta que utilizou para fazer login.
  2. Explore os endpoints organizados por categoria (Autenticação, Gerenciamento de Dispositivos, Gerenciamento de Aplicativos).
  3. Insira os valores dos parâmetros listados no corpo da solicitação da chamada de API que você deseja testar.

    A interface de documentação integrada ajuda você a testar chamadas de API de forma interativa, facilitando a validação de solicitações e a análise de respostas antes de integrá-las aos seus fluxos de trabalho.

Autenticação: Primeira solicitação e obrigatória

Importante: Antes de utilizar qualquer serviço da web do IBM MaaS360, seu aplicativo deve se autenticar e obter um token de autenticação válido. Após a geração do token, ele é válido por 60 minutes ; após esse período, é necessário solicitar um novo token. Todas as chamadas subsequentes ao serviço web devem incluir esse token.

Para ter permissão para solicitar um token de autenticação, o aplicativo deve primeiro estar provisioned within IBM MaaS360 autorizado a utilizar seus serviços da web. Para obter mais informações, consulte “Provisionamento automático de serviços da Web ”.

Credenciais do aplicativo

As credenciais a seguir são utilizadas para autenticar um aplicativo na plataforma IBM MaaS360.

Valores de campo
  • App ID: 30102000_testAPI
  • Versão do aplicativo: 1
  • ID da plataforma: 3
  • Chave de acesso ao aplicativo: jCTjQ762Tp
  • ID de cobrança: 30102000
  • Nome de usuário: Admin_API
  • Senha: adminSafe01

Exemplo de chamada à API: Authentication (authToken)

Terminal
POST /auth/1.0/authenticate/{billingId}

Versão da API: auth1.0

Corpo da solicitação (XML)
xml
<?xml version="1.0" encoding="UTF-8"?>
<authRequest>
 <maaS360AdminAuth>
  <platformID>3</platformID>
  <billingID>30102000</billingID>
  <password>adminSafe01</password>
  <userName>Admin_API</userName>
  <appID>30102000_testAPI</appID>
  <appVersion>1</appVersion>
  <appAccessKey>jCTjQ762Tp</appAccessKey>
 </maaS360AdminAuth>
</authRequest>
Resposta
Uma resposta de autenticação bem-sucedida contém um <authToken> elemento. Extraia e armazene esse valor, pois ele será necessário para todas as chamadas de API subsequentes.
xml
<authToken>9bab5021-d275-4970-952b-0630775f5c3e-IGJAaGQ</authToken>
Vida útil do token
O token de autenticação expira após 60 minutes. Planeje a lógica do seu aplicativo para realizar a autenticação conforme necessário.

Realizando chamadas autenticadas à API

Após a autenticação, todas as solicitações subsequentes devem incluir o token de autorização no cabeçalho da solicitação. MaaS token="<your-auth-token>"O token deve ser formatado exatamente como mostrado no exemplo a seguir, incluindo o MaaS token= prefix e as aspas que o envolvem.

cabeçalhos necessários

Valor/Formato do cabeçalho

Autorização: MaaS token="<your-auth-token>"

BillingId: 30102000

Cabeçalho de autorização de exemplo
Autorização: MaaS token="1cdfaedb-3b37-7abf-b5da-9f755ba73e73-IGPjdBd"
Observação: a omissão do MaaS token= prefix ou das aspas que o cercam resulta em uma falha na autorização.

Exemplo de chamada à API: Ocultar um dispositivo

Este exemplo mostra como marcar um dispositivo como Inactive usando o Hide Device endpoint.

Terminal
POST /devices/1.0/hideDevice/{billingId}

Essa ação marca o dispositivo especificado como inativo no site IBM MaaS360.

Parâmetros

Valor de parâmetro
  • Autorização: MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd"
  • BillingId: 30102000
  • deviceId: Appl73841673

Comando cURL

Depois que você inserir os valores dos parâmetros no portal, a interface preenche automaticamente o seguinte comando ` cURL ` e fica pronta para execução.

Solicitação
curl -X 'POST' \
 'https://services.m3.maas360.com/device-apis/devices/1.0/hideDevice/30102000' \
 -H 'accept: application/xml' \
 -H 'Authorization: MaaS token="1cdfaedb-3b57-4abf-b6da-9f764ba73e73-IGPjBBd"' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'xFblAco: Api_Docs' \
 -d 'deviceId=Appl73841673'
Resposta Esperada
Uma chamada bem-sucedida retorna uma resposta em XML que confirma a ação.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<actionResponse>
 <actionStatus>0</actionStatus>
 <description>Hide action executed successfully</description>
 <maas360DeviceID>Appl73841673</maas360DeviceID>
</actionResponse>

Um <actionStatus> de 0 indica sucesso. O <description> campo exibe uma confirmação legível e <maas360DeviceID> indica o dispositivo sobre o qual foi realizada a ação.

Principais conclusões

  • Faça a autenticação primeiro
    Cada sessão deve começar com uma chamada de autenticação bem-sucedida para obter um token.
  • A validade do token é de 60 minutos
    Incorpore uma lógica de atualização de token em qualquer integração de longa duração.
  • Formate o cabeçalho de autorização corretamente
    Sempre use o MaaS token="your token" formato, e a sintaxe exata é importante.
  • Utilize a documentação integrada ao portal
    A interface interativa ajuda você a testar e gerar cURL comandos sem precisar escrever nenhum código.
  • Configure seu aplicativo antes de chamar a API
    Sem o provisionamento adequado em IBM MaaS360, as solicitações de autenticação falham.

Para obter mais endpoints e casos de uso avançados, consulte a documentação completa da API no Portal IBM MaaS360 em Configuração > API de Serviços Web > Documentação.