Risoluzione dei problemi relativi alla creazione di oggetti tramite Esplora API di FMC

Opzioni per il download

PDF (1.2 MB)
Visualizza con Adobe Reader su diversi dispositivi

Aggiornato:26 giugno 2025

ID documento:223159

Linguaggio senza pregiudizi

La documentazione per questo prodotto è stata redatta cercando di utilizzare un linguaggio senza pregiudizi. Ai fini di questa documentazione, per linguaggio senza di pregiudizi si intende un linguaggio che non implica discriminazioni basate su età, disabilità, genere, identità razziale, identità etnica, orientamento sessuale, status socioeconomico e intersezionalità. Le eventuali eccezioni possono dipendere dal linguaggio codificato nelle interfacce utente del software del prodotto, dal linguaggio utilizzato nella documentazione RFP o dal linguaggio utilizzato in prodotti di terze parti a cui si fa riferimento. Scopri di più sul modo in cui Cisco utilizza il linguaggio inclusivo.

Informazioni su questa traduzione

Cisco ha tradotto questo documento utilizzando una combinazione di tecnologie automatiche e umane per offrire ai nostri utenti in tutto il mondo contenuti di supporto nella propria lingua. Si noti che anche la migliore traduzione automatica non sarà mai accurata come quella fornita da un traduttore professionista. Cisco Systems, Inc. non si assume alcuna responsabilità per l’accuratezza di queste traduzioni e consiglia di consultare sempre il documento originale in inglese (disponibile al link fornito).

Introduzione

In questo documento viene descritto come un amministratore API può eseguire il push in blocco di oggetti di rete, porta e URL in FMC utilizzando API Explorer.

Prerequisiti

Requisiti

Cisco raccomanda la conoscenza dei seguenti argomenti:

Informazioni sulle varie chiamate all'API REST (Application Programming Interface). (Nozioni fondamentali sulle API REST)
Informazioni su API Explorer in FMC (Firepower Management Center) (Informazioni su API Explorer)
Revisione della Guida introduttiva all'API di FMC
Informazioni sui diversi tipi di oggetti in FMC (Gestione oggetti in FMC)

Componenti usati

Firepower Management Center che supporta le API REST (versione 7.4 o successiva) con l'API REST abilitata
API Explorer integrato in FMC

Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.

Limitazioni

Il nome dell'oggetto non può superare i 64 caratteri.
Il nome dell'oggetto non deve contenere spazi all'inizio del nome e punti e virgola alla fine.
Il payload non può contenere più di 1.000 voci in un singolo Bulk Push.
Le dimensioni del payload non possono essere maggiori di 2 MB in un singolo Bulk Push.

Premesse

Le API REST sono sempre più diffuse a causa dell'approccio programmabile leggero che i gestori di rete possono utilizzare per configurare e gestire le loro reti. FMC supporta la configurazione e la gestione utilizzando qualsiasi client REST e utilizzando inoltre l'API explorer integrato.

In questo documento viene descritto come risolvere i problemi relativi alla creazione di oggetti tramite l'API Explorer di Firepower Management Center (FMC). Sia che si utilizzino oggetti di rete, oggetti host o configurazioni FTD, questi passaggi possono aiutare a identificare problemi comuni e implementare soluzioni efficaci.

Gli attributi JSON che rimangono comuni a tutti i tipi di oggetti di rete sono:

Valore - Questo attributo fornisce informazioni quali Valore di rete con CIDR. Ad esempio, l'oggetto host può avere x.x.x.x come indirizzo IP e la rete può avere x.x.x/<prefix> come subnet con CIDR.
Tipo: questo attributo fornisce informazioni sul tipo di oggetto utilizzato per configurare l'oggetto (host, rete, servizio, intervallo e FQDN).
Name - Questo attributo fornisce le informazioni sul nome dell'oggetto
Description - Questo attributo può essere utilizzato per fornire informazioni o commenti utili sull'oggetto
Sostituibile - Una sostituzione di oggetto consente di definire un valore alternativo per un oggetto, che il sistema utilizza per le periferiche specificate. Si tratta di un attributo facoltativo che può essere utilizzato nella creazione di oggetti.

Configurazione

Abilita API in FMC

Abilitare l'API REST su Cisco FMC. Per informazioni dettagliate su "Come abilitare l'API REST" e "Best Practices", fare riferimento a Enable REST API on Cisco FMC

Selezionare Sistema > Configurazione > Preferenze API REST > Seleziona "Abilita API REST"

API Explorer risiede nel centro di gestione e vi si può accedere tramite il centro di gestione:

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

Nota: Se si usa la porta HTTPS standard TCP 443, rimuovere ":<https_port" dall'URL in modo sicuro.

Rilevati errori comuni

Vengono descritti gli errori più comuni che si verificano durante l'utilizzo di Esplora API e del metodo POST per la creazione di oggetti. Il formato corretto per ogni oggetto di rete viene descritto successivamente.

1. Token di accesso non valido:

JSON response for invalid access token Risposta JSON per token di accesso non valido

Nota: Questo errore si verifica quando la sessione è scaduta. Ricaricare Esplora API di FMC e ripetere l'autenticazione.

2. Formato utilizzato non valido:

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

Sample JSON request to create object Richiesta JSON di esempio per creare l'oggetto

Failed JSON response due to missing comma Risposta JSON non riuscita a causa di una virgola mancante

Nota: Questo errore si verifica principalmente quando manca una virgola in formato JSON. Nell'esempio ("value": "10.5.3.20") non ha una virgola che ha causato il problema. Solo l'ultimo attributo in formato JSON non deve avere una virgola altrimenti può causare errori.

3. Input non valido utilizzato nella creazione dell'oggetto:

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

Failed JSON response for invalid type Risposta JSON non riuscita per tipo non valido

Nota: In questo esempio la creazione di oggetti viene tentata nella categoria Hosts con payload JSON per Network Object e ha restituito l'errore "Tipo di input non corrispondente". Utilizzare il formato corretto indicato per ciascun oggetto di rete (host, rete, FQDN, servizio e intervallo).

4. Utilizzo del payload di risposta del metodo GET per la creazione di oggetti

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

GET request to fetch host objects Richiesta GET per recuperare gli oggetti host

Failed JSON response due to missing value attribute Risposta JSON non riuscita a causa di un attributo value mancante

Failed JSON response where object is created in incorrect format Risposta JSON non riuscita in cui l'oggetto è stato creato in un formato non corretto

Nota: In questo esempio l'attributo Value manca nel payload JSON recuperato tramite il metodo GET e il parametro espanso è impostato su default. Esistono attributi obbligatori che possono trovarsi nel payload JSON per la creazione dell'oggetto, ovvero tipo, nome e valore per la maggior parte degli oggetti di rete (host, rete, intervallo, servizio e FQDN). Quando si crea un oggetto utilizzando il payload JSON del metodo GET, utilizzare solo le informazioni relative all'oggetto contenute nell'attributo items e rimuovere l'attributo id in modo che non vi siano conflitti UUID.

Crea oggetto host

Oggetto host singolo

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di un singolo oggetto host:

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

Operazione POST per creare l'oggetto host

Nota: Utilizzare il "Parametro ausiliario" predefinito durante l'operazione POST su un singolo oggetto host.

Oggetto host in blocco

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di oggetti host in blocco:

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

Sample JSON request to create bulk objects Richiesta JSON di esempio per creare oggetti ausiliari

Sample JSON Response after creating bulk objects Risposta JSON di esempio dopo la creazione di oggetti ausiliari

Nota: Quando si creano oggetti host ausiliari, selezionare Parametro ausiliario come True. In un singolo Bulk Push è possibile creare un massimo di 1000 voci utilizzando il metodo POST.

Crea oggetto di rete

Oggetto di rete singolo

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di un singolo oggetto di rete:

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

Sample JSON request to create single network object Richiesta JSON di esempio per creare un singolo oggetto di rete

Oggetto di rete in blocco

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push degli oggetti di rete in blocco:

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

Richiesta JSON di esempio per creare oggetti di rete in blocco

Nota: Quando si creano oggetti di rete ausiliari, selezionare Parametro ausiliario come True. In un singolo Bulk Push è possibile creare un massimo di 1000 voci utilizzando il metodo POST.

Crea oggetto intervallo di rete

Oggetto intervallo di rete singolo

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di un singolo oggetto intervallo:

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

Oggetto intervallo di rete in blocco

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push degli oggetti dell'intervallo in blocco:

[
  {
    "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: Quando si creano oggetti dell'intervallo di massa, selezionare Parametro ausiliario come True. In un singolo Bulk Push è possibile creare un massimo di 1000 voci utilizzando il metodo POST.

Crea oggetto FQDN

Oggetto FQDN singolo

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di un singolo oggetto di rete:

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

Oggetto FQDN in blocco

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push degli oggetti di rete in blocco:

[
  {
    "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: quando si creano oggetti FQDN di massa, selezionare Parametro di massa come True. In un singolo Bulk Push è possibile creare un massimo di 1000 voci utilizzando il metodo POST.

Crea oggetto assistenza

Oggetto servizio singolo

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/protocol portobjects > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push di un singolo oggetto servizio:

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

Formato JSON utilizzato per eseguire il push di un singolo oggetto servizio con intervallo:

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

Nota: quando si definisce l'intervallo di porte in formato JSON, utilizzare le virgolette doppie, ad esempio "porta": "1111-1115" altrimenti si potrebbe verificare l'errore: "descrizione": "Entità non elaborabile - Carattere imprevisto ('-' (codice 45)): Prevista virgola per separare le voci Object alla riga: 4, colonna: 17"

Oggetto Bulk Service

Passare a Oggetto > /api/fmc_config/v1/domain/{domainUUID}/object/protocol portobjects > POST e fare clic su Prova.

Formato JSON utilizzato per eseguire il push degli oggetti di servizi in blocco:

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

Nota: quando si creano oggetti di servizi ausiliari, selezionare Parametro ausiliario come True. In un singolo Bulk Push è possibile creare un massimo di 1000 voci utilizzando il metodo POST.