Solucionar problemas de criação de objetos usando o FMC API Explorer

Introdução

Este documento descreve como um administrador de API pode enviar objetos de rede, porta e URL em massa para o FMC usando o API Explorer.

Pré-requisitos

Requisitos

A Cisco recomenda que você tenha conhecimento destes tópicos:

• Compreensão de várias chamadas REST API (Application Programming Interface, Interface de programação de aplicativos). (Conceitos básicos da API REST)
• Entendendo o API Explorer no FMC (Firepower Management Center) (Sobre o API Explorer)
• Revisão do Guia de início rápido da API do FMC
• Compreensão dos diferentes tipos de objetos no FMC (Object Management in FMC)

Componentes Utilizados

• Firepower Management Center que oferece suporte a APIs REST (versão 7.4 ou superior) com API REST habilitada
• API Explorer integrado no FMC

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Limitações

• O FMC não aceita que o nome do objeto tenha mais de 64 caracteres.
• O Nome do Objeto não deve ter espaço no início do nome do objeto e ponto-e-vírgula no final.
• A carga não pode conter mais de 1.000 entradas em um único Envio em Massa.
• O tamanho da carga não pode ser maior que 2MB em um único Envio em Massa.

Informações de Apoio

As APIs REST são cada vez mais populares devido à abordagem programável leve que os gerentes de rede podem usar para configurar e gerenciar suas redes. O FMC oferece suporte à configuração e ao gerenciamento usando qualquer cliente REST e também o explorador de API integrado.

Este artigo fornece etapas de solução de problemas para resolver problemas encontrados durante a criação de objetos por meio do Firepower Management Center (FMC) API Explorer. Esteja você trabalhando com objetos de rede, objetos de host ou configurações de FTD, essas etapas podem ajudar a identificar problemas comuns e implementar soluções eficazes.

Os atributos JSON que permanecem comuns entre todos os tipos de objetos de rede são:

1. Valor - Este atributo fornece informações como o valor de rede com CIDR, por exemplo, o objeto de host pode ter x.x.x.x como um IP e a rede pode ter x.x.x/<prefixo> como sub-rede com CIDR.
2. Tipo - Este atributo fornece informações sobre o tipo de objeto usado para configurar o objeto (host, rede, serviço, intervalo e FQDN).
3. Nome - Este atributo fornece as informações sobre o nome do objeto
4. Descrição - Este atributo pode ser usado para fornecer algumas informações úteis ou comentários sobre o objeto
5. Substituível - Uma substituição de objeto permite que você defina um valor alternativo para um objeto, que o sistema usa para os dispositivos que você especificar. Este é um atributo opcional que pode ser usado na criação de objetos.

Configuração

Habilitar API no FMC

Ative a API REST no Cisco FMC. Para obter informações detalhadas sobre "Como ativar a API REST" e "Práticas recomendadas", consulte Ativar a API REST no Cisco FMC

Navegue até System > Configuration > REST API Preferences > Select "Enable REST API"

O API Explorer reside no centro de gerenciamento e pode ser acessado através do centro de gerenciamento em:

https://<management_center_IP_or_name>:<https_port>/api/api-explorer 

Note: Se a porta HTTPS padrão TCP 443 for usada, remova com segurança ":<https_port" do url.

Erros comuns encontrados

Estamos discutindo os erros mais comuns encontrados ao usar o explorador de API e o método POST para criar objetos. O formato correto para cada objeto de rede é discutido depois dele.

1. Token de acesso inválido:

Resposta JSON para token de acesso inválido

Note: Este erro é encontrado quando a sessão expira. Recarregue o FMC API explorer e autentique novamente.

2. Formato inválido usado:

{
  "name": "API_1",
  "type": "Host",
  "value": "10.5.3.20"
  "description": "Test Description"
}

Solicitação JSON de exemplo para criar objeto

Falha na resposta JSON devido a uma vírgula ausente

Note: Este erro é encontrado principalmente quando há uma vírgula ausente no formato JSON. No exemplo ("valor": "10.5.3.20") não tem uma vírgula que causou essa falha. Somente o último Atributo no formato JSON não deve ter uma vírgula, caso contrário, ele pode causar falha.

3. Entrada Inválida usada na criação do objeto:

{
  "name": "net2",
  "value": "1.1.0.0/24",
  "overridable": false,
  "description": "Network obj 2",
  "type": "Network"
}

Falha na resposta JSON para tipo inválido

Note: Neste exemplo, a criação de objeto é tentada na categoria Hosts com payload JSON para Network Object e resultou no erro "Incompatibilidade de tipo de entrada". Use o formato correto designado para cada Objeto de Rede (Hosts, Rede, FQDN, Serviço e Intervalo).

4. Usando carga útil de resposta do método GET para criação de Objeto

{
      "links": {
        "self": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/hosts/00000000-0000-0ed3-0000-034359741703",
        "parent": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/networkaddresses"
      },
      "type": "Host",
      "name": "API_2",
      "id": "00000000-0000-0ed3-0000-034359741703"
}

Solicitação GET para buscar objetos de host

Falha na resposta JSON devido a atributo de valor ausente

Falha na resposta JSON em que o objeto é criado no formato incorreto

Note: Neste exemplo, o atributo Value está ausente na carga útil JSON buscada usando o método GET e o parâmetro expand está definido como padrão. Há atributos obrigatórios que podem estar na carga JSON para a criação de objetos, que é o tipo, o nome e o valor para a maioria dos objetos de rede (hosts, rede, intervalo, serviço e FQDN). Ao criar um objeto usando a carga útil JSON do método GET, use somente as informações relacionadas ao objeto que estão dentro do atributo items e remova o atributo id para que não haja nenhum conflito de UUID.

Criar objeto de host

Objeto de Host Único

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/hosts > POST e clique em Experimente.

Formato JSON usado para enviar por push um único objeto de host:

{
  "name": "Obj_API_100.1.1.1",
  "type": "Host",
  "value": "100.1.1.1",
  "description": "Host Object Pushed via API"
}

Operação POST para criar objeto de host

Note: Use o "Parâmetro em massa" padrão ao usar a operação POST para um único objeto de host.

Objeto de Host em Massa

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/hosts > POST e clique em Experimente.

Formato JSON usado para enviar objetos de host em massa:

[
	{
	"name": "Obj_API_172.16.0.1",
	"type": "Host",
	"value": "172.16.0.1",
	"description": "Bulk API Operation"
	},
	{
	"name": "Obj_API_172.16.0.2",
	"type": "Host",
	"value": "172.16.0.2",
	"description": "Bulk API Operation"
	}
]

Solicitação JSON de exemplo para criar objetos em massa

Resposta JSON de exemplo após a criação de objetos em massa

Note: Ao criar objetos de host em massa, selecione Parâmetro em Massa como Verdadeiro. Em um único Envio em massa, no máximo 1000 entradas podem ser criadas usando o método POST.

Criar objeto de rede

Único objeto de rede

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/networks > POST e clique em Experimente.

Formato JSON usado para distribuir um único objeto de rede:

{
  "name": "Obj_API_network",
  "value": "7.0.0.0/24",
  "overridable": false,
  "description": "Single Network object created",
  "type": "Network"
}

Exemplo de solicitação JSON para criar um único objeto de rede

Objeto de rede em massa

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/networks > POST e clique em Experimente.

Formato JSON usado para enviar objetos de rede em massa:

[
  {
    "name": "Obj_API_net1",
    "value": "1.0.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  },
  {
    "name": "Obj_API_net2",
    "value": "1.1.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  }
]

Exemplo de solicitação JSON para criar objetos de rede em massa

Note: Ao criar objetos de rede em massa, selecione Bulk Parameter como True. Em um único Envio em massa, no máximo 1000 entradas podem ser criadas usando o método POST.

Criar Objeto de Intervalo de Rede

Objeto de Intervalo de Rede Único

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/ranges > POST e clique em Experimente.

Formato JSON usado para enviar por push um objeto de intervalo único:

{
  "name": "Obj_API_TestRange",
  "value": "10.2.30.40-10.2.30.50",
  "type": "Range",
  "description": "Create Single Range Object"
}

Objeto de Intervalo de Rede em Massa

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/ranges > POST e clique em Experimente.

Formato JSON usado para enviar objetos de intervalo em massa:

[
  {
    "name": "Obj_API_TestRange1",
    "value": "10.4.30.40-10.4.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_TestRange2",
    "value": "10.5.30.40-10.5.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  }
]

Note: Ao criar objetos de intervalo em massa, selecione Parâmetro em massa como Verdadeiro. Em um único Envio em massa, no máximo 1000 entradas podem ser criadas usando o método POST.

Criar Objeto FQDN

Objeto FQDN Único

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/fqdns > POST e clique em Experimente.

Formato JSON usado para distribuir um único objeto de rede:

{
  "name": "TestFQDN",
  "type": "FQDN",
  "value": "cloud.cisco.com",
  "dnsResolution": "IPV4_ONLY",
  "description": "Create Single FQDN Object"
}

Objeto FQDN em Massa

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/fqdns > POST e clique em Experimente.

Formato JSON usado para enviar objetos de rede em massa:

[
  {
    "name": "Obj_API_FQDN_1",
    "type": "FQDN",
    "value": "downloads.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_FQDN_2",
    "type": "FQDN",
    "value": "support.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  }
]

Observação: ao criar objetos FQDN em massa, selecione Parâmetro em Massa como Verdadeiro. Em um único Envio em massa, no máximo 1000 entradas podem ser criadas usando o método POST.

Criar objeto de serviço

Objeto de serviço único

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/protoportobjects > POST e clique em Experimente.

Formato JSON usado para enviar por push um único objeto de serviço:

{
  "name": "Obj_API_Telnet_Port",
  "protocol": "TCP",
  "port": 23,
  "type": "ProtocolPortObject"
}

Formato JSON usado para enviar por push um único objeto de serviço com intervalo:

{
  "name": "Obj_API_obj1",
  "protocol": "UDP",
  "port": "1025-65535",
  "type": "ProtocolPortObject"
}

Observação: quando você definir o intervalo de portas no formato JSON, use aspas duplas, por exemplo "porta": "1111-1115" caso contrário, você pode encontrar o erro: "Descrição": "Entidade não processável - Caractere inesperado ('-' (código 45)): esperava uma vírgula para separar as entradas de Objeto na linha: 4, coluna: 17"

Objeto de Serviço em Massa

Navegue até Objeto > /api/fmc_config/v1/domain/{domainUID}/object/protoportobjects > POST e clique em Experimente.

Formato JSON usado para enviar objetos de serviço em massa:

[
  {
    "name": "Obj_API_UDP_Port",
    "protocol": "UDP",
    "port": 123,
    "type": "ProtocolPortObject"
  },
  {
    "name": "Obj_API_TCP_Range",
    "protocol": "TCP",
    "port": "1025-65535",
    "type": "ProtocolPortObject"
  }
]

Observação: ao criar objetos de serviço em massa, selecione Parâmetro em massa como Verdadeiro. Em um único Envio em massa, no máximo 1000 entradas podem ser criadas usando o método POST.

Troubleshooting

• Consulte o documento para obter o código de status HTTP (Fundamentos da API REST)
• As credenciais do usuário não podem ser usadas para interfaces REST API e GUI simultaneamente, e o usuário é desconectado sem aviso se usado para ambos.
• Todas as solicitações REST são registradas nesses dois arquivos de log no FMC. Procure sua URL (por exemplo, ../object/hosts) com a operação correta (Se você estiver procurando por erro para a operação GET, certifique-se de que seu log inicie algo como GET ...objeto/hosts)

tail -f /var/opt/CSCOpx/MDC/tomcat/logs/stdout.logs  
tail -f /var/opt/CSCOpx/MDC/log/operation/usmsharedsvcs.log