Dépannage de la création d'objets avec l'Explorateur API FMC

Introduction

Ce document décrit comment un administrateur d'API peut envoyer des objets réseau, de port et d'URL en masse vers FMC à l'aide de l'Explorateur d'API.

Conditions préalables

Exigences

Cisco vous recommande de prendre connaissance des rubriques suivantes :

• Compréhension des divers appels de l'API REST (Application Programming Interface). (API REST - Notions de base)
• Présentation de l'Explorateur d'API dans FMC (Firepower Management Center) (À propos de l'Explorateur d'API)
• Révision du guide de démarrage rapide de l'API FMC
• Présentation des différents types d'objets dans FMC (Gestion des objets dans FMC)

Composants utilisés

• Firepower Management Center qui prend en charge les API REST (version 7.4 ou ultérieure) avec l'API REST activée
• API Explorer intégré dans FMC

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. Si votre réseau est en ligne, assurez-vous de bien comprendre l’incidence possible des commandes.

Limites

• FMC n'accepte pas que le nom de l'objet dépasse 64 caractères.
• Le champ Nom de l'objet ne doit pas contenir d'espace au début du nom de l'objet et un point-virgule à la fin.
• La charge utile ne peut pas contenir plus de 1 000 entrées dans une seule transmission en masse.
• La taille de la charge utile ne peut pas être supérieure à 2 Mo dans une seule transmission en masse.

Informations générales

Les API REST sont de plus en plus populaires en raison de l'approche programmable légère que les administrateurs réseau peuvent utiliser pour configurer et gérer leurs réseaux. FMC prend en charge la configuration et la gestion à l’aide de tout client REST et de l’explorateur d’API intégré.

Cet article décrit les étapes de dépannage permettant de résoudre les problèmes rencontrés lors de la création d'objets via l'Explorateur d'API du Centre de gestion Firepower (FMC). Que vous utilisiez des objets réseau, des objets hôtes ou des configurations FTD, ces étapes peuvent vous aider à identifier les problèmes courants et à mettre en oeuvre des solutions efficaces.

Les attributs JSON qui restent communs à tous les types d'objets réseau sont les suivants :

1. Valeur - Cet attribut fournit des informations comme la valeur réseau avec CIDR, par exemple, l'objet hôte peut avoir x.x.x.x comme adresse IP et le réseau peut avoir x.x.x.x/<prefix> comme sous-réseau avec CIDR.
2. Type - Cet attribut fournit des informations sur le type d'objet utilisé pour configurer l'objet (hôte, réseau, service, plage et nom de domaine complet).
3. Nom - Cet attribut fournit des informations sur le nom de l'objet
4. Description - Cet attribut peut être utilisé pour fournir des informations utiles ou des commentaires sur l'objet
5. Remplaçable - Un remplacement d'objet vous permet de définir une autre valeur pour un objet, que le système utilise pour les périphériques que vous spécifiez. Il s'agit d'un attribut facultatif qui peut être utilisé lors de la création d'objets.

Configuration

Activer l'API sur FMC

Activez l'API REST sur Cisco FMC. Pour des informations détaillées sur « Comment activer l'API REST » et « Meilleures pratiques », référez-vous à Activer l'API REST sur Cisco FMC

Accédez à System > Configuration > REST API Preferences > Select "Enable REST API"

L'explorateur d'API réside sur le centre de gestion et est accessible via le centre de gestion à l'adresse :

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

Remarque : Si le port HTTPS standard TCP 443 est utilisé, supprimez en toute sécurité ":<https_port" de l'URL.

Erreurs courantes rencontrées

Nous examinons les erreurs les plus courantes rencontrées lors de l'utilisation de l'explorateur d'API et de la méthode POST pour créer des objets. Le format correct de chaque objet réseau est présenté ci-après.

1. Jeton d'accès non valide :

Réponse JSON pour jeton d'accès non valide

Remarque : Cette erreur se produit lorsque la session a expiré. Rechargez l'explorateur d'API FMC et réauthentifiez-vous.

2. Format non valide utilisé :

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

Exemple de demande JSON pour créer un objet

Échec de la réponse JSON en raison d'une virgule manquante

Remarque : Cette erreur se produit principalement lorsqu'il manque une virgule au format JSON. Dans l'exemple ("value" : "10.5.3.20") n'a pas de virgule qui a causé cette erreur. Seul le dernier attribut au format JSON ne doit pas comporter de virgule, sinon il peut provoquer un échec.

3. Entrée non valide utilisée dans la création d'objets :

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

Échec de la réponse JSON pour un type non valide

Remarque : Dans cet exemple, la création d'objets est tentée dans la catégorie Hosts avec la charge utile JSON pour l'objet Network et a entraîné l'erreur "Incompatibilité du type d'entrée". Utilisez le format approprié désigné pour chaque objet réseau (hôtes, réseau, nom de domaine complet, service et plage).

4. Utilisation de la charge utile de réponse de méthode GET pour la création d'objets

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

Requête GET pour récupérer des objets hôtes

Échec de la réponse JSON en raison d'un attribut de valeur manquant

Échec de la réponse JSON où l'objet est créé dans un format incorrect

Remarque : Dans cet exemple, l'attribut Value est manquant dans la charge utile JSON extraite à l'aide de la méthode GET et le paramètre expand est défini sur default. Il existe des attributs obligatoires qui peuvent être dans la charge utile JSON pour la création d'objet qui est le type, le nom et la valeur pour la plupart des objets réseau (hôtes, réseau, plage, service et FQDN). Lors de la création d'un objet à l'aide de la charge utile JSON de la méthode GET, utilisez uniquement les informations liées à l'objet qui se trouvent dans l'attribut items et supprimez l'attribut id afin d'éviter tout conflit d'UUID.

Créer un objet hôte

Objet hôte unique

Accédez à Object > /api/fmc_config/v1/domain/{domainUID}/object/hosts > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre un objet hôte unique :

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

Opération POST pour créer un objet hôte

Remarque : Utilisez le paramètre par défaut Bulk Parameter lors de l'utilisation de l'opération POST sur un seul objet hôte.

Bulk Host, objet

Accédez à Object > /api/fmc_config/v1/domain/{domainUID}/object/hosts > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre des objets hôtes en masse :

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

Exemple de demande JSON pour créer des objets en masse

Exemple de réponse JSON après la création d'objets en masse

Remarque : Lors de la création d'objets hôtes en bloc, sélectionnez Bulk Parameter comme True. Dans un seul envoi en masse, un maximum de 1 000 entrées peut être créé à l'aide de la méthode POST.

Créer un objet réseau

Objet réseau unique

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre un seul objet réseau :

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

Exemple de requête JSON pour créer un objet réseau unique

Objet réseau en bloc

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre des objets réseau en masse :

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

Exemple de requête JSON pour créer des objets réseau en masse

Remarque : Lors de la création d'objets réseau en bloc, sélectionnez Bulk Parameter comme True. Dans un seul envoi en masse, un maximum de 1 000 entrées peut être créé à l'aide de la méthode POST.

Créer un objet de plage réseau

Objet de plage réseau unique

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST et cliquez sur Try it Out.

Format JSON utilisé pour pousser un objet de plage unique :

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

objet de plage réseau en bloc

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST et cliquez sur Try it Out.

Format JSON utilisé pour pousser des objets de plage en bloc :

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

Remarque : Lorsque vous créez des objets de plage en bloc, sélectionnez Bulk Parameter comme True. Dans un seul envoi en masse, un maximum de 1 000 entrées peut être créé à l'aide de la méthode POST.

Créer un objet FQDN

Objet FQDN unique

Accédez à Object > /api/fmc_config/v1/domain/{domainUID}/object/fqdns > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre un seul objet réseau :

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

Objet FQDN en bloc

Accédez à Object > /api/fmc_config/v1/domain/{domainUID}/object/fqdns > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre des objets réseau en masse :

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

Remarque : lors de la création d'objets FQDN en bloc, sélectionnez Bulk Parameter comme True. Dans un seul envoi en masse, un maximum de 1 000 entrées peut être créé à l'aide de la méthode POST.

Créer un objet service

Objet de service unique

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre un seul objet de service :

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

Format JSON utilisé pour pousser un seul objet de service avec une plage :

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

Remarque : lorsque vous définissez une plage de ports au format JSON, utilisez des guillemets doubles, par exemple "port" : "1111-1115" sinon vous pouvez rencontrer l'erreur : "description" : "Entité non traitable - Caractère inattendu ('-' (code 45)) : attendait une virgule pour séparer les entrées d'objet à la ligne : 4, colonne : 17"

Objet de service en bloc

Accédez à Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST et cliquez sur Try it Out.

Format JSON utilisé pour transmettre des objets de service en masse :

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

Remarque : lors de la création d'objets de service en bloc, sélectionnez Bulk Parameter comme True. Dans un seul envoi en masse, un maximum de 1 000 entrées peut être créé à l'aide de la méthode POST.

Dépannage

• Reportez-vous au document pour connaître le code d'état HTTP (REST API Basics)
• Les informations d'identification de l'utilisateur ne peuvent pas être utilisées simultanément pour les interfaces REST API et GUI, et l'utilisateur est déconnecté sans avertissement s'il est utilisé pour les deux.
• Toutes les requêtes REST sont consignées dans ces deux fichiers journaux sur FMC. Recherchez votre URL (par ex. .../object/hosts) avec l'opération correcte(Si vous recherchez une erreur pour l'opération GET, assurez-vous que votre journal démarre quelque chose comme GET ...objet/hôtes)

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