Problembehandlung bei der Objekterstellung mit FMC API Explorer

Download-Optionen

PDF (1.2 MB)
Mit Adobe Reader auf verschiedenen Geräten anzeigen

Aktualisiert:26. Juni 2025

Dokument-ID:223159

Inklusive Sprache

In dem Dokumentationssatz für dieses Produkt wird die Verwendung inklusiver Sprache angestrebt. Für die Zwecke dieses Dokumentationssatzes wird Sprache als „inklusiv“ verstanden, wenn sie keine Diskriminierung aufgrund von Alter, körperlicher und/oder geistiger Behinderung, Geschlechtszugehörigkeit und -identität, ethnischer Identität, sexueller Orientierung, sozioökonomischem Status und Intersektionalität impliziert. Dennoch können in der Dokumentation stilistische Abweichungen von diesem Bemühen auftreten, wenn Text verwendet wird, der in Benutzeroberflächen der Produktsoftware fest codiert ist, auf RFP-Dokumentation basiert oder von einem genannten Drittanbieterprodukt verwendet wird. Hier erfahren Sie mehr darüber, wie Cisco inklusive Sprache verwendet.

Informationen zu dieser Übersetzung

Cisco hat dieses Dokument maschinell übersetzen und von einem menschlichen Übersetzer editieren und korrigieren lassen, um unseren Benutzern auf der ganzen Welt Support-Inhalte in ihrer eigenen Sprache zu bieten. Bitte beachten Sie, dass selbst die beste maschinelle Übersetzung nicht so genau ist wie eine von einem professionellen Übersetzer angefertigte. Cisco Systems, Inc. übernimmt keine Haftung für die Richtigkeit dieser Übersetzungen und empfiehlt, immer das englische Originaldokument (siehe bereitgestellter Link) heranzuziehen.

Einleitung

In diesem Dokument wird beschrieben, wie ein API-Administrator Netzwerk-, Port- und URL-Objekte in Massen mithilfe des API-Explorers an FMC übertragen kann.

Voraussetzungen

Anforderungen

Cisco empfiehlt, dass Sie über Kenntnisse in folgenden Bereichen verfügen:

Kenntnis der verschiedenen REST API (Application Programming Interface)-Aufrufe. (Grundlagen der REST-API)
API Explorer in FMC (FirePOWER Management Center) (Informationen zum API Explorer)
Durchsicht der FMC API Quick Start Guide
Verstehen verschiedener Objekttypen in FMC (Object Management in FMC)

Verwendete Komponenten

Firepower Management Center, das REST-APIs (Version 7.4 oder höher) mit aktivierter REST-API unterstützt
API-Explorer in FMC integriert

Die Informationen in diesem Dokument beziehen sich auf Geräte in einer speziell eingerichteten Testumgebung. Alle Geräte, die in diesem Dokument benutzt wurden, begannen mit einer gelöschten (Nichterfüllungs) Konfiguration. Wenn Ihr Netzwerk in Betrieb ist, stellen Sie sicher, dass Sie die möglichen Auswirkungen aller Befehle kennen.

Einschränkungen

Das FMC akzeptiert keine Namen von Objekten, die mehr als 64 Zeichen enthalten.
Der Objektname darf nicht mit einem Leerzeichen am Anfang des Objektnamens und einem Semikolon am Ende beginnen.
Die Nutzlast darf nicht mehr als 1.000 Einträge in einem Bulk Push enthalten.
Die Payload-Größe darf nicht mehr als 2 MB in einem Bulk Push betragen.

Hintergrundinformationen

REST-APIs werden aufgrund des einfachen programmierbaren Ansatzes, den Netzwerkmanager zur Konfiguration und Verwaltung ihrer Netzwerke verwenden können, immer beliebter. FMC unterstützt die Konfiguration und das Management über einen beliebigen REST-Client sowie den integrierten API-Explorer.

Dieser Artikel enthält Schritte zur Fehlerbehebung, mit denen Probleme behoben werden können, die beim Erstellen von Objekten über den API-Explorer des FirePOWER Management Center (FMC) auftreten. Unabhängig davon, ob Sie mit Netzwerkobjekten, Hostobjekten oder FTD-Konfigurationen arbeiten, können diese Schritte bei der Identifizierung gängiger Probleme und der Implementierung effektiver Lösungen helfen.

Folgende JSON-Attribute sind bei allen Netzwerkobjekttypen gleich:

Wert - Dieses Attribut stellt Informationen bereit, z. B. Netzwerkwert mit CIDR. Hostobjekte können x.x.x.x als IP und Netzwerke können x.x.x.x/<Präfix> als Subnetz mit CIDR haben.
Type: Dieses Attribut enthält Informationen zum Objekttyp, der zum Konfigurieren von Objekten verwendet wird (Host, Netzwerk, Service, Bereich und FQDN).
Name: Dieses Attribut enthält Informationen zum Namen des Objekts.
Beschreibung - Dieses Attribut kann verwendet werden, um nützliche Informationen oder Kommentare zum Objekt bereitzustellen.
Außerkraftsetzbar - Mit einer Objektüberschreibung können Sie einen alternativen Wert für ein Objekt definieren, den das System für die von Ihnen angegebenen Geräte verwendet. Dies ist ein optionales Attribut, das zum Erstellen von Objekten verwendet werden kann.

Konfiguration

API auf FMC aktivieren

Aktivierung der REST-API auf Cisco FMC Weitere Informationen zur Aktivierung der REST-API und zu Best Practices finden Sie unter Enable REST API on Cisco FMC.

Navigieren Sie zu System > Configuration > REST API Preferences > Wählen Sie "Enable REST API" aus.

Der API-Explorer befindet sich im Management Center und kann über das Management Center aufgerufen werden:

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

Anmerkung: Wenn der Standard-HTTPS-Port TCP 443 verwendet wird, entfernen Sie ":<https_port" sicher von der URL.

Häufige Fehler

Wir besprechen die häufigsten Fehler, die bei der Verwendung des API-Explorers und der POST-Methode zum Erstellen von Objekten auftreten. Anschließend wird das richtige Format für jedes Netzwerkobjekt besprochen.

1. Ungültiges Zugriffstoken:

JSON response for invalid access token JSON-Antwort für ungültiges Zugriffstoken

Anmerkung: Dieser Fehler tritt auf, wenn die Sitzung abgelaufen ist. Erneutes Laden des FMC API-Explorers und erneute Authentifizierung

2. Ungültiges Format:

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

Sample JSON request to create object Beispiel für JSON-Anforderung zum Erstellen eines Objekts

Failed JSON response due to missing comma JSON-Antwort fehlgeschlagen, da Komma fehlt

Anmerkung: Dieser Fehler tritt meistens auf, wenn ein Komma im JSON-Format fehlt. Im Beispiel ("value": "10.5.3.20") kein Komma, das diesen Fehler verursacht hat. Nur das letzte Attribut im JSON-Format darf kein Komma enthalten, sonst kann es zu Fehlern kommen.

3. Ungültige Eingabe bei der Objekterstellung:

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

Failed JSON response for invalid type JSON-Antwort mit ungültigem Typ fehlgeschlagen

Anmerkung: In diesem Beispiel wird versucht, ein Objekt in der Kategorie Hosts mit JSON-Nutzlast für Network Object zu erstellen, und es wurde der Fehler "Input type mismatch" (Eingabetyp stimmt nicht überein) ausgegeben. Verwenden Sie das für jedes Netzwerkobjekt (Hosts, Netzwerk, FQDN, Service und Bereich) festgelegte Format.

4. Verwenden der Antwortnutzlast der GET-Methode für die Objekterstellung

{
      "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 GET-Anforderung zum Abrufen von Hostobjekten

Failed JSON response due to missing value attribute Fehler bei JSON-Antwort aufgrund eines fehlenden Wertattributs

Failed JSON response where object is created in incorrect format Fehlgeschlagene JSON-Antwort, bei der das Objekt im falschen Format erstellt wurde

Anmerkung: In diesem Beispiel fehlt das Value-Attribut in der JSON-Nutzlast, die mit der GET-Methode abgerufen wurde, und der erweiterte Parameter ist auf den Standardwert festgelegt. Es gibt obligatorische Attribute, die in JSON-Nutzlast für die Objekterstellung enthalten sein können, d. h. Typ, Name und Wert für die meisten Netzwerkobjekte (Hosts, Netzwerk, Bereich, Service und FQDN). Wenn Sie ein Objekt mit der JSON-Payload der GET-Methode erstellen, verwenden Sie nur objektbezogene Informationen, die sich im Items-Attribut befinden, und entfernen Sie das id-Attribut, sodass kein UUID-Konflikt auftritt.

Hostobjekt erstellen

Einzelhost-Objekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen eines einzelnen Hostobjekts:

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

POST-Vorgang zum Erstellen eines Hostobjekts

Anmerkung: Verwenden Sie die Standardeinstellung "Bulk Parameter" bei Verwendung des POST-Vorgangs für ein einzelnes Hostobjekt.

Bulk-Hostobjekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen von Bulk-Host-Objekten:

[
	{
	"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 Beispiel für JSON-Anforderung zum Erstellen von Massenobjekten

Sample JSON Response after creating bulk objects Beispiel für JSON-Antwort nach dem Erstellen von Massenobjekten

Anmerkung: Wenn Sie Bulk-Host-Objekte erstellen, wählen Sie Bulk Parameter als True aus. In einem einzelnen Bulk Push können maximal 1000 Einträge mithilfe der POST-Methode erstellt werden.

Netzwerkobjekt erstellen

Einzelnes Netzwerkobjekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen eines einzelnen Netzwerkobjekts:

{
  "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 Beispiel für JSON-Anforderung zum Erstellen eines einzelnen Netzwerkobjekts

Massen-Netzwerkobjekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen von Massen-Netzwerkobjekten:

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

Beispiel für JSON-Anforderung zum Erstellen von Massen-Netzwerkobjekten

Anmerkung: Wählen Sie beim Erstellen von Massen-Netzwerkobjekten Massen-Parameter als True aus. In einem einzelnen Bulk Push können maximal 1000 Einträge mithilfe der POST-Methode erstellt werden.

Netzwerkbereichsobjekt erstellen

Einzelnes Netzwerkbereichsobjekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen von Objekten mit einem Bereich:

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

Massen-Netzwerkbereichsobjekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST, und klicken Sie auf Try it Out.

JSON-Format für das Push von Objekten mit großem Bereich:

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

Anmerkung: Wenn Sie Massenbereichsobjekte erstellen, wählen Sie Massenparameter als True aus. In einem einzelnen Bulk Push können maximal 1000 Einträge mithilfe der POST-Methode erstellt werden.

FQDN-Objekt erstellen

Einzelnes FQDN-Objekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen eines einzelnen Netzwerkobjekts:

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

Massen-FQDN-Objekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen von Massen-Netzwerkobjekten:

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

Hinweis: Wenn Sie mehrere FQDN-Objekte erstellen, wählen Sie Bulk Parameter als True aus. In einem einzelnen Bulk Push können maximal 1000 Einträge mithilfe der POST-Methode erstellt werden.

Service-Objekt erstellen

Einzelnes Service-Objekt

Navigieren Sie zu Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolProtocols > POST, und klicken Sie auf Try it Out.

JSON-Format zum Übertragen eines einzelnen Serviceobjekts:

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

JSON-Format zum Übertragen eines einzelnen Serviceobjekts mit Bereich:

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

Hinweis: Wenn Sie einen Port-Bereich im JSON-Format definieren, verwenden Sie doppelte Anführungszeichen, z. B. "port": "1111-1115", andernfalls kann ein Fehler auftreten: "Beschreibung": "Unverarbeitbare Einheit - Unerwartetes Zeichen ('-' (Code 45)): erwartet ein Komma, um Objekteinträge in Zeile zu trennen: 4, Spalte 17"

Massendienstobjekt