Contents

Introdução

Pré-requisitos

Requisitos

Componentes Utilizados

Limitações

Informações de Apoio

Configuração

Habilitar API no FMC

Erros comuns encontrados

Criar objeto de host

Objeto de Host Único

Objeto de Host em Massa

Criar objeto de rede

Único objeto de rede

Objeto de rede em massa

Criar Objeto de Intervalo de Rede

Objeto de Intervalo de Rede Único

Objeto de Intervalo de Rede em Massa

Criar Objeto FQDN

Objeto FQDN Único

Objeto FQDN em Massa

Criar objeto de serviço

Objeto de serviço único

Objeto de Serviço em Massa

Troubleshooting

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