Solucionar problemas de creación de objetos mediante el Explorador de API FMC

Introducción

Este documento describe cómo un administrador de API puede enviar objetos de red, puerto y URL de forma masiva a FMC mediante el Explorador de API.

Prerequisites

Requirements

Cisco recomienda que tenga conocimiento sobre estos temas:

• Información sobre varias llamadas de API REST (interfaz de programación de aplicaciones). (Aspectos básicos de la API REST)
• Introducción al Explorador de API en FMC (Firepower Management Center) (Acerca del Explorador de API)
• Revisión de la Guía de inicio rápido de FMC API
• Comprensión de los diferentes tipos de objetos en FMC (Object Management in FMC)

Componentes Utilizados

• Firepower Management Center que admite API REST (versión 7.4 o superior) con API REST habilitada
• Explorador de API integrado en FMC

La información que contiene este documento se creó a partir de los dispositivos en un ambiente de laboratorio específico. Todos los dispositivos que se utilizan en este documento se pusieron en funcionamiento con una configuración verificada (predeterminada). Si tiene una red en vivo, asegúrese de entender el posible impacto de cualquier comando.

Limitaciones

• El CSP no acepta que el nombre del objeto tenga más de 64 caracteres.
• El nombre del objeto no debe tener espacios al principio del nombre del objeto ni punto y coma al final.
• La carga útil no puede contener más de 1000 entradas en una única transferencia masiva.
• El tamaño de la carga útil no puede ser superior a 2 MB en una sola transferencia masiva.

Antecedentes

Las API REST son cada vez más populares debido al enfoque programable ligero que los administradores de red pueden utilizar para configurar y administrar sus redes. FMC admite la configuración y la gestión mediante cualquier cliente REST y también mediante el explorador de API integrado.

En este artículo se proporcionan los pasos para solucionar los problemas encontrados al crear objetos mediante el Explorador de API de Firepower Management Center (FMC). Tanto si trabaja con objetos de red, objetos host o configuraciones de FTD, estos pasos pueden ayudarle a identificar problemas comunes e implementar soluciones eficaces.

Los atributos JSON que siguen siendo comunes entre todos los tipos de objetos de red son:

1. Valor: Este atributo proporciona información como el valor de la red con CIDR; por ejemplo, el objeto host puede tener x.x.x.x como IP y la red puede tener x.x.x.x/<prefix> como subred con CIDR.
2. Tipo: este atributo proporciona información sobre el tipo de objeto utilizado para configurar el objeto (host, red, servicio, intervalo y FQDN).
3. Nombre: este atributo proporciona la información sobre el nombre del objeto
4. Descripción: este atributo se puede utilizar para proporcionar información útil o comentarios sobre el objeto
5. Overrideable - Un reemplazo de objeto permite definir un valor alternativo para un objeto, que el sistema utiliza para los dispositivos especificados. Se trata de un atributo opcional que se puede utilizar para crear objetos.

Configuración

Activar API en FMC

Habilite la API REST en Cisco FMC. Para obtener información detallada sobre "Cómo habilitar la API REST" y "Prácticas recomendadas", consulte Habilitar la API REST en Cisco FMC

Vaya a System > Configuration > REST API Preferences > Select "Enable REST API"

El Explorador de API reside en el centro de administración y se puede acceder a él a través del centro de administración en:

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

Nota: Si se utiliza el puerto HTTPS estándar TCP 443, quite de forma segura ":<https_port" de la url.

Errores comunes encontrados

Estamos hablando de los errores más comunes que encontramos al utilizar el explorador de API y el método POST para crear objetos. El formato correcto para cada objeto de red se discute después de él.

1. Token de acceso no válido:

Respuesta JSON para token de acceso no válido

Nota: Este error se produce cuando la sesión ha caducado. Recargue el explorador de API FMC y vuelva a autenticar.

2. Formato no válido utilizado:

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

Solicitud JSON de ejemplo para crear un objeto

Respuesta JSON fallida debido a que falta una coma

Nota: Este error se produce principalmente cuando falta una coma en formato JSON. En el ejemplo ("value": "10.5.3.20") no tiene una coma que haya causado este error. Sólo el último Atributo en formato JSON no debe tener una coma; de lo contrario, puede provocar un error.

3. Entrada no válida utilizada en la creación de objetos:

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

Respuesta JSON errónea para tipo no válido

Nota: En este ejemplo, se intenta la creación de objetos en la categoría Hosts con carga JSON para el objeto Network y se produjo el error "Tipo de entrada no coincidente". Utilice el formato correcto designado para cada objeto de red (hosts, red, FQDN, servicio e intervalo).

4. Uso de la carga útil de respuesta del método GET para la creación de objetos

{
      "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"
}

Solicitud GET para obtener objetos host

Respuesta JSON fallida debido a un atributo de valor faltante

Respuesta JSON fallida donde el objeto se crea en formato incorrecto

Nota: En este ejemplo, falta el atributo Value en la carga útil JSON obtenida mediante el método GET y el parámetro extended está establecido en el valor predeterminado. Existen atributos obligatorios que pueden incluirse en la carga JSON para la creación de objetos, que son el tipo, el nombre y el valor de la mayoría de los objetos de red (hosts, red, rango, servicio y FQDN). Al crear un objeto mediante la carga JSON del método GET, utilice únicamente la información relacionada con el objeto que se encuentra dentro del atributo items y quite el atributo id para que no haya ningún conflicto de UUID.

Crear objeto host

Objeto de host único

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar un solo objeto host:

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

Operación POST para crear un objeto host

Nota: Utilice el "parámetro masivo" predeterminado mientras utiliza la operación POST para un único objeto host.

Objeto de host masivo

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar objetos host masivos:

[
	{
	"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"
	}
]

Solicitud JSON de ejemplo para crear objetos masivos

Respuesta JSON de ejemplo después de crear objetos masivos

Nota: Al crear objetos host masivos, seleccione Bulk Parameter como True. En una única transferencia masiva se pueden crear un máximo de 1000 entradas mediante el método POST.

Crear objeto de red

Objeto de red único

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar un solo objeto de red:

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

Solicitud JSON de ejemplo para crear un único objeto de red

Objeto de red masivo

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar objetos de red masivos:

[
  {
    "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"
  }
]

Solicitud JSON de ejemplo para crear objetos de red masivos

Nota: Al crear objetos de red masivos, seleccione Bulk Parameter como True. En una única transferencia masiva se pueden crear un máximo de 1000 entradas mediante el método POST.

Crear objeto de intervalo de red

Objeto de rango de red único

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/rangos > POST y haga clic en Pruébelo.

Formato JSON utilizado para insertar un solo objeto de rango:

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

Objeto de intervalo de red masivo

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/rangos > POST y haga clic en Pruébelo.

Formato JSON utilizado para insertar objetos de rango masivo:

[
  {
    "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"
  }
]

Nota: Al crear objetos de rango masivo, seleccione Bulk Parameter como True. En una única transferencia masiva se pueden crear un máximo de 1000 entradas mediante el método POST.

Crear objeto FQDN

Objeto FQDN único

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar un solo objeto de red:

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

Objeto FQDN masivo

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar objetos de red masivos:

[
  {
    "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"
  }
]

Nota: Al crear objetos FQDN masivos, seleccione Bulk Parameter como True. En una única transferencia masiva se pueden crear un máximo de 1000 entradas mediante el método POST.

Crear objeto de servicio

Objeto de servicio único

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar un solo objeto de servicio:

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

Formato JSON utilizado para enviar un único objeto de servicio con intervalo:

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

Nota: Cuando defina un intervalo de puertos en formato JSON, utilice comillas dobles como, por ejemplo, "puerto": "1111-1115" de lo contrario puede encontrar un error: "descripción": "Entidad no procesable - Carácter inesperado ('-' (código 45)): esperaba que una coma separara las entradas de objeto en la línea: 4, columna: 17"

Objeto de servicio masivo

Vaya a Objeto > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST y haga clic en Pruébelo.

Formato JSON utilizado para enviar objetos de servicio masivo:

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

Nota: Al crear objetos de servicio masivo, seleccione Bulk Parameter como True. En una única transferencia masiva se pueden crear un máximo de 1000 entradas mediante el método POST.

Troubleshoot

• Consulte el documento para obtener el código de estado HTTP (Aspectos básicos de la API REST)
• Las credenciales de usuario no se pueden utilizar para las interfaces API REST y GUI simultáneamente, y el usuario se desconecta sin previo aviso si se utiliza para ambas.
• Todas las solicitudes REST se registran en estos dos archivos de registro en FMC. Busque su URL (p. ej. .../object/hosts) con la operación correcta(Si está buscando un error para la operación GET, asegúrese de que su registro inicia 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