Catalyst Center API's gebruiken met Python

Inleiding

In dit document wordt beschreven hoe u de verschillende API's kunt gebruiken die beschikbaar zijn in Cisco Catalyst Center met Python.

Voorwaarden

Vereisten

Basiskennis over:

• Cisco Catalyst Center
• API's
• Python

Gebruikte componenten

• Cisco Catalyst Center 2.3.5.x
• Python 3.x.x

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.

Opmerking: Het Cisco Technical Assistance Center (TAC) biedt geen technische ondersteuning voor Python. Als u problemen ondervindt met Python, neem dan contact op met Python Support voor technische hulp.

Configureren

Overzicht

Cisco Catalyst Center heeft veel API's beschikbaar. Om te controleren welke API's kunnen worden gebruikt, bladert u in Catalyst Center naar Platform > Developer Toolkit > API's.

Catalyst Center API's Pagina

Elke API heeft zijn eigen doel, afhankelijk van de informatie of de actie die moet worden uitgevoerd op Catalyst Center. Om de API's te laten werken, moet een token worden gebruikt om correct te authenticeren naar Catalyst Center en een succesvolle API-respons te krijgen. De token identificeert de privileges voor de REST beller dienovereenkomstig.

Het is ook belangrijk om de componenten te identificeren die deel uitmaken van een API die als volgt zijn:

• URL: Eindpunt dat toegang biedt tot een specifieke bron.
• Methode: Alle API's moeten een methode bevatten. Het definieert de actie/bewerking die de client wil uitvoeren voor het specifieke eindpunt. Voorbeelden: POST, GET, PUT, DELETE.
• Koptekst: geeft aanvullende informatie over het verzoek in de indeling sleutelwaardeparen. De autorisatiekoptekst biedt bijvoorbeeld een verificatiemethode met referenties.
• Parameters: Variabelen die specifieke instructies geven aan het eindpunt met behulp van de API. De parameters kunnen deel uitmaken van de URL van het eindpunt.
• Payload: gegevens die tijdens de API-oproep naar het eindpunt moeten worden verzonden.

Opmerking: Voor meer gedetailleerde informatie over elke API die beschikbaar is in Catalyst Center, raadpleegt u de API Reference guide.

Modules

Gebruikte Python-modules:

• verzoeken: Deze module maakt het mogelijk om HTTP/1.1-verzoeken naar specifieke URL's te verzenden. Voor meer informatie over de module raadpleegt u de handleiding voor de aanvraagmodule.
• base64: Biedt codeer- en decoderingsfuncties. Voor meer informatie over de module, raadpleeg de base64 module gids.
• json: Deze module maakt het mogelijk om specifieke gegevens uit API's-respons te halen. Voor meer informatie over de module, raadpleeg de json module gids.

Opmerking: raadpleeg de documentatie over het installeren van Python-modules voor meer informatie over het installeren van Python-modules.

Token genereren

De API genaamd Authentication API moet worden gebruikt om een nieuwe token te genereren.

Authenticatie-API:

POST      https:///dna/system/api/v1/auth/token

Het is belangrijk om te vermelden dat het token dat wordt gegenereerd 1 uur geldig is. Na 1 uur moet een nieuwe token worden gegenereerd met behulp van dezelfde API die hierboven wordt genoemd.

In een nieuw Python-bestand importeert u de modules (requests, base64 en json) gevolgd door vier variabelen te maken:

import requests
import base64
import json

user = 'user'    # User to login to Catalyst Center
password = 'password'    # Password to login to Catalyst Center
token = ''    # Variable to store the token string
authorizationBase64 = ''   # Variable that stores Base64 encoded string of "username:password"

Authenticatie API ondersteunt Basic Authentication Token in de header. Basic Auth is een methode die kan worden gebruikt om te authenticeren naar een eindpunt, met een gebruikersnaam en wachtwoord gescheiden door een dubbele punt (gebruikersnaam: wachtwoord). Beide waarden zijn gecodeerd met base64 en het eindpunt decodeert de aanmeldingsreferenties en controleert of de gebruiker toegang heeft of niet.

Om de Base64-geecondeerde string voor onze gebruikersnaam en wachtwoord te maken, wordt de base64 module gebruikt. Hiervoor wordt de b64encode functie gebruikt.

byte_string = (f'{user}:{password}').encode("ascii")
authorizationBase64 = base64.b64encode(byte_string).decode()

Uit de bovenstaande code is een variabele byte_string gemaakt met behulp van de functie ‘.encode("ascii"). Dit komt omdat de functie base64.b64encode een bytes-achtig object vereist. Merk ook op dat gebruikers- en wachtwoordvariabelen werden gebruikt om de tekenreeksindeling ‘user:password’ te behouden. Ten slotte werd een base64-gecodeerde byte-string gemaakt met de gebruiker en het wachtwoord. Met behulp van de methode ‘decode()’ werd de waarde omgezet in str object.

Om dit te verifiëren, kunt u de waarde voor de variabele authorisationBase64 afdrukken:

print(authorizationBase64)

Voorbeeld uitvoer:

am9yZ2QhbDI6Sm9yZ2VhbDXxXxXx

Let op: base64 is geen versleutelingsalgoritme. Het mag niet worden gebruikt voor veiligheidsdoeleinden. De authenticatie-API ondersteunt ook AES-sleutelversleuteling als autorisatietoken in de header, wat meer veiligheid biedt.

Nu een base64-gecodeerde string is gemaakt met behulp van de gebruiker en het wachtwoord om te authenticeren, Catalyst Center, is het tijd om door te gaan met de API Authentication API call met behulp van de module aanvragen. De functie request maakt het ook mogelijk om een antwoordobject te krijgen dat de tekst van het verzoek bevat.

Syntaxis van de methode:

requests.request(“method”, “url”, **kwargs)

**kwargs betekent elke parameter die in het verzoek wordt doorgegeven, bijvoorbeeld cookies, user-agents, payload, headers, enzovoort.

De Authentication API specificeert dat de methode POST is, de URL is "/dna/system/api/v1/auth/token" en de basis auth moet worden gespecificeerd in de Header.

Deze variabelen worden aangemaakt om ze te gebruiken voor de functie request().

url = https:///api/system/v1/auth/token
headers = {
	‘content-type’: “application/json”,
	‘Authorization’: ‘Basic ’ + authorizationBase64
	}

Voor de variabele headers zijn twee dingen gespecificeerd. De eerste is het inhoudstype, dat het mediatype aangeeft van de bron die naar het eindpunt wordt verzonden (dit helpt voor het eindpunt om de gegevens nauwkeurig te parsen en te verwerken). De tweede is Authorization, waarbij in dit geval de variabele authorisationBase64 (waarin onze base64-geecondeerde string is opgeslagen) als parameter wordt verzonden om te authenticeren naar Catalyst Center.

Ga nu verder met het gebruik van de functie request() om de API-aanroep uit te voeren. De volgende code toont de syntaxis van de functie:

response = requests.request(“POST”, url, headers=headers)

De responsvariabele is gemaakt om de gegevens van onze API-oproep op te slaan.

Als u de verkregen reactie wilt afdrukken, gebruikt u de afdrukfunctie samen met de methode text() in de variabele response. De methode text() genereert een str-object met het antwoord dat is ontvangen van Catalyst Center.

print(response.text)

Voorbeeld uitvoer:

{“Token”:“eyJhbGci0iJSUzI1NiIsInR5JK09s1zVmNjk0NjhkNTFhNDJ1ZWeLCU291cmNlIjoiaW50ZXJuYWwiLCW2vMPUbU0JNlqxOXNe1jMzY1LTQ5MWEtODljNC0yZmE2YjVhM2 
!--- Output is supressed

Opmerking: Als Catalyst Center een zelf ondertekend certificaat gebruikt, kan het API-verzoek mislukken met de volgende fout:

requests.exceptions.SSLError: HTTPSConnectionPool(host='X.X.X.X', port=443): Max retries exceeded with url: /api/system/v1/auth/token (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1000)')))

Om dit probleem op te lossen, moet u de verificatieparameter als false toevoegen aan de aanvraagfunctie. Hiermee wordt de verificatie van het SSL-certificaat vanaf het eindpunt (Catalyst Center) genegeerd.

response = requests.request(“POST”, url, headers=headers, verify=False)

Uit het antwoord ontvangen van de API authenticatie oproep, merk op dat de structuur is vergelijkbaar met een woordenboek in Python, maar het is een str object.

Gebruik de functie type() om het type van een object te valideren.

print(type(response.text))

Wat de volgende uitvoer retourneert:

Voor praktische doeleinden hoeft alleen de tokenwaarde te worden geëxtraheerd uit het antwoord dat is ontvangen van de API, niet de hele tekenreeks, omdat, om de andere Catalyst Center API's te gebruiken, alleen het token als parameter moet worden doorgegeven.

Aangezien het antwoord van de API-aanroep een structuur heeft die lijkt op een woordenboek in Python, maar het objecttype str is, moet het genoemde object worden omgezet in een woordenboek met behulp van de json-module. Dit extraheert de tokenwaarde uit de hele string die van de API is ontvangen.

Om dit te bereiken converteert de functie json.loads() de string naar een woordenboek om later alleen de tokenwaarde te extraheren en deze direct toe te wijzen aan onze token variabele.

token = json.loads(response.text)  # Converting the response.text string value into a dictionary (It is creating a JSON object).
token = (token["Token"])  # Extracting just the token value by specifying the key as a parameter.

Om te controleren of de token-variabele alleen de token als waarde heeft, gaat u verder met afdrukken.

print(token)

Voorbeeld uitvoer:

eyJhbGci0iJSUzI1NiIsInR5JK09s1zVmNjk0NjhkNTFhNDJ1ZWeLCU291cmNlIjoiaW50ZXJuYWwiLCW2vMPUbU0JNlqxOXNe1jMzY1LTQ5MWEtODljNC0yZmE2YjVhM2 
!--- Output is supressed

Tip: Aangezien elk gegenereerd token standaard binnen 1 uur verloopt, kan een Python-methode die de code bevat om een token te genereren, worden gemaakt en aangeroepen elke keer dat een token verloopt, zonder dat het hele programma hoeft te worden uitgevoerd door alleen de gemaakte methode aan te roepen.

Een API testen

Nu het token met succes is toegewezen aan de token-variabele, kunnen beschikbare Catalyst Center API's worden gebruikt.

In dit geval wordt de Cisco DNA Center Nodes Configuration Summary API getest.

Cisco DNA Center Nodes Configuration Summary

GET     https:///dna/intent/api/v1/nodes-config

Deze API biedt details over de huidige configuratie van Catalyst Center, zoals NTP-server geconfigureerd, knooppuntnaam, intra-clusterlink, LACP-modus, enzovoort.

De Cisco DNA Center Nodes Configuration Summary API specificeert, in dit geval, dat de gebruikte methode GET is, de URL is "/dna/intent/api/v1/nodes-config" en, aangezien de token string is geëxtraheerd en toegewezen aan de token variabele, deze keer wordt de token doorgegeven als een variabele in de header van de API call als ‘X-Auth-Token’: gevolgd door de token.

Hiermee wordt het verzoek aan Catalyst Center geverifieerd voor elke API-oproep die wordt uitgevoerd. Vergeet niet dat elke token 1 uur duurt. Na 1 uur moet een nieuwe token worden gegenereerd om API-oproepen naar Catalyst Center te blijven doen.

Ga verder met het maken van de variabelen om de API te testen:

nodeInfo_url = "https:///dna/intent/api/v1/nodes-config"
nodeInfo_headers = {
    'X-Auth-Token': token
}

nodeInfoResponse = requests.request("GET", nodeInfo_url, headers=nodeInfo_headers)

nodeInfo_url variabele is gemaakt om de URL van onze API op te slaan. nodeInfo_headers variabele slaat de headers voor onze API op. In dit geval werden ‘X-Auth-Token:’ en de token-variabele doorgegeven als parameters om het verzoek met succes te verifiëren aan Catalyst Center. Ten slotte slaat de variabele nodeInfoResponse de respons van de API op.

Om het ontvangen antwoord te valideren, kunt u de functie print() gebruiken.

Voorbeeld uitvoer:

{"response": {"nodes": [{"name": "Catalyst Center", "id": "ea5dbec1-fbb6-4339-9242-7694eb1cXxXx", "network": [{"slave": ["enp9s0"], "lacp_supported": true, "intra_cluster_link": false, "interface": "enterprise", "inet6": {}, "inet": {"routes": [{"netmask": "255.255.0.0"
!--- Output is supressed

Opmerking: Als een zelf ondertekend certificaat in gebruik is in Catalyst Center, kan het API-verzoek mislukken met de volgende fout:

requests.exceptions.SSLError: HTTPSConnectionPool(host='X.X.X.X', port=443): Max retries exceeded with url: /api/system/v1/auth/token (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1000)')))

Om dit probleem op te lossen, moet u de parameter verifieren als FALSE aan het verzoek toevoegen. Hierdoor wordt de verificatie van het SSL-certificaat vanaf het eindpunt (Catalyst Center) onderdrukt.

nodeInfoResponse = requests.request("GET", nodeInfo_url, headers=nodeInfo_headers, verify=False)

Het antwoord van de API kan moeilijk te lezen zijn. Met behulp van de json() module kan de respons worden afgedrukt in een meer leesbare string. Eerst moet de API-respons in een JSON-object worden geladen met behulp van de functie json.loads() gevolgd door de functie json.dumps():

jsonFormat = (json.loads(nodeInfoResponse.text)) # Creating a JSON object from the string received from the API response.
print(json.dumps(jsonFormat, indent=1)) # Printing the response in a more readable string using the dumps() function.

json.dumps: Deze functie retourneert het JSON-object dat als parameter is gebruikt in een tekenreeks met JSON-opmaak.

inspringing: deze parameter definieert het inspringing-niveau voor de tekenreeks met de JSON-opmaak.

Voorbeeld uitvoer:

{
  "response": {
    "nodes": [
      {
        "name": "X.X.X.X",
        "id": "ea5dbec1-fbb6-4339-9242-7694eb1xXxX",
        "network": [
          {
            "slave": [
              "enp9s0"
            ],
            "lacp_supported": true,
            "intra_cluster_link": false,
!--- Output is supressed

API's met header-parameters

Er zijn enkele API's die vereisen dat sommige parameters in de Header worden verzonden om te werken zoals verwacht. In dit geval wordt de Get Client Enrichment Details API getest.

GET        https:///dna/intent/api/v1/client-enrichment-details

Om te controleren welke Headers Parameters vereist zijn voor de API om te werken zoals verwacht, navigeert u naar Platform > Developer Toolkit > API's > Gegevens voor clientverrijking ophalen en klikt u op de naam van de API. Er wordt een nieuw venster geopend en onder de optie Parameters worden de headers en parameters weergegeven die nodig zijn om de API te laten werken.

In dit geval kan voor de parameter entity_type, volgens de beschrijving, de waarde network_user_id of mac_address zijn en moet de parameter entity_value de waarde bevatten voor het gedefinieerde entiteitstype.

Om hiermee verder te gaan, worden twee nieuwe variabelen gedefinieerd, entity_type en entity_value met hun corresponderende waarden:

entity_type = 'mac_address'   #This value could be either 'network_user_id' or 'mac_address'.
entity_value = 'e4:5f:02:ff:xx:xx'    #Depending of the 'entity_type' used, need to add the corresponding value for 'entity_value'. In this case, 'mac_address' value was chosen for 'entity_type' parameter so, a MAC Address was assigned to the 'entity_value' parameter.

Er worden ook nieuwe variabelen gemaakt om de API-aanroep uit te voeren. De URL van de API-aanroep wordt opgeslagen in de variabele userEnrichment_url. Headers worden opgeslagen in de variabele userEnrichmentHeaders. Het ontvangen antwoord wordt opgeslagen in de variabele userEnrichmentResponse.

userEnrichment_url = "https:///dna/intent/api/v1/user-enrichment-details"

userEnrichmentHeaders = {
'X-Auth-Token': token,
'entity_type': entity_type,
'entity_value': entity_value,
}

userEnrichmentResponse = requests.request("GET", userEnrichment_url, headers=userEnrichmentHeaders)

Zoals u kunt zien werden uit de userEnrichmentHeaders, entity_type en entity_value variabelen doorgegeven als Header parameters voor de API-aanroep, samen met de token variabele.

Gebruik de functie print() om het ontvangen antwoord te valideren.

print(userEnrichmentResponse.text)

Voorbeeld uitvoer:

[ {
  "userDetails" : {
    "id" : "E4:5F:02:FF:xx:xx",
    "connectionStatus" : "CONNECTED",
    "tracked" : "No",
    "hostType" : "WIRELESS",
    "userId" : null,
    "duid" : "",
    "identifier" : "jonberrypi-1",
    "hostName" : "jonberrypi-1",
    "hostOs" : null,
    "hostVersion" : null,
    "subType" : "RaspberryPi-Device",
    "firmwareVersion" : null,
    "deviceVendor" : null,
    "deviceForm" : null,
    "salesCode" : null,
    "countryCode" : null,
    "lastUpdated" : 1721225220000,
    "healthScore" : [ {
      "healthType" : "OVERALL",
      "reason" : "",
      "score" : 10
    }, {
      "healthType" : "ONBOARDED",
      "reason" : "",
      "score" : 4
!--- Output is suppressed

API's met queryparameters

Queryparameters kunnen worden gebruikt om een specifiek aantal resultaten te filteren dat door een API wordt geretourneerd. Deze parameters worden toegevoegd aan de URL van de API.

De API-oproep Apparaatlijst ophalen is getest.

GET          https://10.88.244.133/dna/intent/api/v1/network-device

De Get Device List API retourneert een lijst met alle apparaten die zijn toegevoegd in Catalyst Center. Als gegevens voor een specifiek apparaat worden gevraagd, kunnen queryparameters helpen om specifieke informatie te filteren.

Om te controleren welke queryparameters beschikbaar zijn voor de API, gaat u naar Platform > Developer Toolkit > API's > Apparaatlijst ophalen en klikt u op de naam van de API. Er wordt een nieuw venster geopend en onder de optie Parameters worden queryparameters weergegeven die beschikbaar zijn voor de API.

In dit voorbeeld worden managementIpAddress en serialNumber-queryparameters gebruikt (houd er rekening mee dat het niet nodig is om alle queryparameters voor de API-oproep te gebruiken). Ga verder met het maken en toewijzen van de bijbehorende waarden voor beide queryparameters.

managementIpAddress = '10.82.143.250'
serialNumber = 'FDO25160X9L'

Zoals hierboven vermeld, worden de queryparameters toegevoegd aan de URL van de API, met name aan het einde van de IT, met behulp van een ‘?’ gevolgd door de queryparameters.

In het geval van meerdere queryparameters die worden gebruikt, wordt er een & - teken tussen geplaatst om een zogenaamde querytekenreeks te vormen.

In het volgende voorbeeld ziet u hoe u de queryparameters toevoegt aan de variabele deviceListUrl waarin de URL van de API-aanroep wordt opgeslagen.

deviceListUrl = "https:///dna/intent/api/v1/network-device?managementIpAddresss=" + managementIpAddress + "&serialNumber=" + serialNumber

Merk op dat de variabelen die eerder zijn gemaakt, aan de URL-tekenreeks zijn toegevoegd. Met andere woorden, de hele string van de URL ziet er als volgt uit:

deviceListUrl = "https:///dna/intent/api/v1/network-device?managementIpAddresss=10.82.143.250&serialNumber=FDO25160X9L"

Ga verder met de API-aanroep, de variabele deviceListHeaders wordt gemaakt om de API-headers samen met de token-variabele als parameter op te slaan en de variabele deviceListResponse slaat de API-respons op.

deviceListHeaders = {
            'X-Auth-Token': token,
        }

deviceListResponse = requests.request("GET", deviceListUrl, headers=deviceListHeaders)

Om het ontvangen antwoord te valideren, kunt u de functie print() gebruiken.

print(deviceListResponse.text)

Voorbeeld uitvoer:

{"response":[{"family":"Switches and Hubs","description":"Cisco IOS Software [Cupertino], Catalyst L3 Switch Software (CAT9K_IOSXE), Version 17.9.4a, RELEASE SOFTWARE (fc3) Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2023 by Cisco Systems, Inc. Compiled Fri 20-Oct-23 10:44 by mcpre","lastUpdateTime":1721205664979,"deviceSupportLevel":"Supported","softwareType":"IOS-XE","softwareVersion":"17.9.4a","serialNumber":"FDO25160X9L","inventoryStatusDetail":"

Tip: Als u de reactie op een leesbaardere manier wilt afdrukken, kunt u de functies json.loads() en json.dumps() gebruiken die in de sectie API testen worden beschreven.