Problemen oplossen bij het maken van objecten met FMC API Explorer

Inleiding

In dit document wordt beschreven hoe een API-beheerder Network-, Port- en URL-objecten in bulk naar FMC kan pushen met behulp van API Explorer.

Voorwaarden

Vereisten

Cisco raadt kennis van de volgende onderwerpen aan:

• Inzicht in verschillende REST API (Application Programming Interface) aanroepen. (BASISPRINCIPES VAN REST API)
• API Explorer begrijpen in FMC (Firepower Management Center) (Over de API Explorer)
• Beoordeling van de FMC API Quick Start Guide
• Inzicht in verschillende soorten objecten in FMC (objectbeheer in FMC)

Gebruikte componenten

• Firepower Management Center dat REST API's (versie 7.4 of hoger) ondersteunt met REST API ingeschakeld
• API Explorer geïntegreerd in FMC

De informatie in dit document is gebaseerd op de apparaten in een specifieke laboratoriumomgeving. Alle apparaten die in dit document worden beschreven, hadden een opgeschoonde (standaard)configuratie. Als uw netwerk live is, moet u zorgen dat u de potentiële impact van elke opdracht begrijpt.

Beperkingen

• De naam van het object mag niet meer dan 64 tekens bevatten.
• Objectnaam mag geen spatie hebben aan het begin van de objectnaam en een puntkomma aan het einde.
• De payload mag niet meer dan 1.000 items bevatten in één bulkpush.
• De payload kan niet groter zijn dan 2 MB in één bulkpush.

Achtergrondinformatie

REST API's worden steeds populairder vanwege de lichtgewicht programmeerbare aanpak die netwerkbeheerders kunnen gebruiken om hun netwerken te configureren en te beheren. FMC ondersteunt configuratie en beheer met behulp van elke REST-client en ook met behulp van de ingebouwde API-verkenner.

In dit artikel worden stappen beschreven voor het oplossen van problemen die zich voordoen bij het maken van objecten via de API Explorer van Firepower Management Center (FMC). Of u nu werkt met netwerkobjecten, hostobjecten of FTD-configuraties, deze stappen kunnen u helpen veelvoorkomende problemen te identificeren en effectieve oplossingen te implementeren.

De JSON-kenmerken die bij alle objecttypen van het netwerk nog steeds voorkomen, zijn:

1. Waarde - Dit attribuut biedt informatie zoals Netwerkwaarde met CIDR. Een hostobject kan bijvoorbeeld x.x.x.x.x als IP hebben en een netwerk kan x.x.x.x/<prefix> als subnet met CIDR hebben.
2. Type - Dit kenmerk geeft informatie over het objecttype dat wordt gebruikt om het object te configureren (host, netwerk, service, bereik en FQDN).
3. Naam - Dit attribuut geeft de informatie over de naam van het object
4. Beschrijving - Dit kenmerk kan worden gebruikt om nuttige informatie of commentaar over het object te geven
5. Overschrijfbaar - Met een objectoverschrijving kunt u een alternatieve waarde definiëren voor een object, die het systeem gebruikt voor de apparaten die u opgeeft. Dit is een optioneel attribuut dat kan worden gebruikt bij het maken van objecten.

Configuratie

API inschakelen voor FMC

REST API inschakelen op Cisco FMC. Voor gedetailleerde informatie over "Hoe REST API inschakelen" en "Best Practices" verwijzen we naar Enable REST API on Cisco FMC

Navigeer naar Systeem > Configuratie > REST API-voorkeuren > Selecteer "REST API inschakelen"

De API Explorer bevindt zich in het beheercentrum en is toegankelijk via het beheercentrum:

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

Opmerking: Als standaard HTTPS-poort TCP 443 wordt gebruikt, verwijder dan veilig ":<https_port" uit de URL.

Veelvoorkomende fouten aangetroffen

We bespreken de meest voorkomende fouten die we tegenkomen bij het gebruik van API explorer en POST-methode om objecten te maken. Het juiste formaat voor elk netwerkobject wordt hierna besproken.

1. Ongeldige toegangstoken:

JSON-respons voor ongeldige toegangstoken

Opmerking: deze fout treedt op wanneer de sessie is verlopen. FMC API explorer opnieuw laden en opnieuw verifiëren.

2. Ongeldige verkoopvorm:

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

Voorbeeld van JSON-verzoek om object te maken

Mislukte JSON-respons door ontbrekende komma

Opmerking: Deze fout treedt meestal op wanneer er een ontbrekende komma in JSON-indeling is. In het voorbeeld ("waarde": "10.5.3.20") heeft geen komma die deze fout heeft veroorzaakt. Alleen het laatste Attribuut in JSON-indeling mag geen komma bevatten, anders kan het een fout veroorzaken.

3. Ongeldige invoer die is gebruikt bij het maken van objecten:

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

Mislukte JSON-respons voor ongeldig type

Opmerking: in dit voorbeeld wordt het maken van objecten geprobeerd in de categorie Hosts met JSON-payload voor Network Object en dit resulteerde in een fout "Invoertype mismatch". Gebruik de juiste indeling die is toegewezen voor elk netwerkobject (hosts, netwerk, FQDN, service en bereik).

4. De payload van de GET-methode gebruiken voor het maken van objecten

{
      "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-verzoek om hostobjecten op te halen

Mislukte JSON-respons door attribuut voor ontbrekende waarde

Mislukte JSON-reactie waarbij object in onjuiste indeling is gemaakt

Opmerking: In dit voorbeeld ontbreekt het attribuut Value in de JSON-payload die is opgehaald met de methode GET en is de uitgebreide parameter ingesteld op standaard. Er zijn verplichte attributen die kunnen worden gebruikt in JSON payload voor het maken van objecten, dat is type, naam en waarde voor de meeste netwerkobjecten (hosts, netwerk, bereik, service en FQDN). Wanneer u een object maakt met de JSON-payload van GET-methode, gebruikt u alleen objectgerelateerde informatie die zich in het attribuut items bevindt en verwijdert u het id-attribuut zodat er geen UUID-conflict is.

Hostobject maken

Single Host Object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt voor het pushen van één hostobject:

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

POST-bewerking om hostobject te maken

Opmerking: gebruik standaard "Bulkparameter" tijdens het gebruik van POST-bewerking voor één hostobject.

Bulkhost-object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om bulkhostobjecten te pushen:

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

Voorbeeld van JSON-verzoek om bulkobjecten te maken

Voorbeeld van JSON-respons na het maken van bulkobjecten

Opmerking: Selecteer Bulkparameter als Waar bij het maken van bulkhostobjecten. In één bulkpush kunnen maximaal 1000 items worden gemaakt met de POST-methode.

Netwerkobject maken

Enkelvoudig netwerkobject

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST en klik op Probeer het uit.

JSON-indeling gebruikt om één netwerkobject te pushen:

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

Voorbeeld van JSON-verzoek om één netwerkobject te maken

Bulknetwerkobject

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om bulknetwerkobjecten te pushen:

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

Voorbeeld van JSON-verzoek om bulknetwerkobjecten te maken

Opmerking: Selecteer Bulkparameter als Waar bij het maken van bulknetwerkobjecten. In één bulkpush kunnen maximaal 1000 items worden gemaakt met de POST-methode.

Object Network Range maken

Single Network Range Object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om een object met één bereik te pushen:

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

Object Bulk Network Range

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om objecten met een bulkbereik te pushen:

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

Opmerking: Selecteer Bulkparameter als Waar bij het maken van objecten met een bulkbereik. In één bulkpush kunnen maximaal 1000 items worden gemaakt met de POST-methode.

FQDN-object maken

Eén FQDN-object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST en klik op Probeer het uit.

JSON-indeling gebruikt om één netwerkobject te pushen:

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

Bulk FQDN-object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om bulknetwerkobjecten te pushen:

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

Opmerking: Selecteer Bulkparameter als Waar bij het maken van bulk-FQDN-objecten. In één bulkpush kunnen maximaal 1000 items worden gemaakt met de POST-methode.

Serviceobject maken

Single Service-object

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolprojects > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om één serviceobject te pushen:

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

JSON-indeling gebruikt om één serviceobject met bereik te pushen:

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

Opmerking: Wanneer u het poortbereik in JSON-indeling definieert, gebruikt u dubbele aanhalingstekens, bijvoorbeeld "poort": "1111-1115", anders kunt u een fout tegenkomen: "beschrijving": "Niet-verwerkbare entiteit - Onverwacht teken ('-' (code 45): verwachtte dat komma's de objectvermeldingen zouden scheiden op regel: 4, kolom: 17"

Bulkserviceobject

Navigeer naar Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolprojects > POST en klik op Probeer het uit.

JSON-indeling die wordt gebruikt om bulkserviceobjecten te pushen:

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

Opmerking: Selecteer Bulkparameter als Waar bij het maken van bulkserviceobjecten. In één bulkpush kunnen maximaal 1000 items worden gemaakt met de POST-methode.

Problemen oplossen

• Verwijs het document naar HTTP-statuscode (REST API Basics)
• Gebruikersreferenties kunnen niet tegelijkertijd voor zowel REST API- als GUI-interfaces worden gebruikt en de gebruiker wordt zonder waarschuwing uitgelogd als deze voor beide wordt gebruikt.
• Alle REST-verzoeken worden aangemeld bij deze twee logbestanden op FMC. Zoek naar uw URL (bijv. .../object/hosts) met de juiste bewerking (Als u op zoek bent naar een fout voor de GET-bewerking, moet u ervoor zorgen dat uw log zoiets start als GET ...object/hosts)

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