Работа с API Catalyst Center

[Ambarish Kumar]

Понимание вызовов API
API (интерфейс прикладного программирования) — это способ взаимодействия одной программы с другой. Вызов API или запрос API — это сообщение, отправляемое на сервер с просьбой предоставить API услугу или информацию.
В нашей лабораторной установке, поскольку мы взаимодействуем с Catalyst Center, вызовы API, которые мы выполняем через Postman (клиент), взаимодействуют с конечной точкой API, присутствующей в Catalyst Center, для получения некоторой информации или вызова некоторой услуги (конфигурации) в Catalyst Center.
Intent API — это REST API
северного направления
, который раскрывает определенные возможности платформы Cisco Catalyst Center. RESTful Cisco Catalyst Center Intent API использует HTTPS-глаголы (GET, POST, PUT и DELETE) со структурами JSON для обнаружения и управления сетью.
Понимание HTTPS-глаголов, используемых в лаборатории:
POST
— в этой лабораторной работе мы будем в основном использовать вызовы POST. POST используется для отправки данных на сервер CATALYST CENTER с целью выполнения любых изменений/обновлений конфигурации.
GET —
мы будем использовать их редко, однако это еще один важный глагол. GET используется для запроса информации из Catalyst Center.
Вызовы API Catalyst Center
Создание сайтов
Первым шагом в настройке автоматизации и обеспечения качества является создание сетевой иерархии.
URL

• https://{{CatalystCenter-ip}}/dna/intent/api/v1/site
  Заголовки
  – x-auth-token = {{CatalystCenter_token}}
  Пример тела запроса
  — это создаст область с названием «United States» в разделе Global.
  {
  «type»: «area»,
  "site": {
  "area": {
  "name": "United States",
  "parentName": "Global"
  }
  }
  }
  ![Screenshot 2025-09-10 at 8.37.34 PM.png]
  Пример тела запроса
  — это создаст область с названием «Нью-Йорк» в разделе «Глобальный/Соединенные Штаты».
  {
  «type»: «area»,
  «site»: {
  "area": {
  "name": "New York",
  "parentName": "Глобальный/Соединенные Штаты"
  }
  }
  }
  ![Screenshot 2025-09-10 at 8.39.34 PM.png]
  Создание зданий и этажей в разделах «Сайты»
  Здесь мы создадим здания и этажи под объектами.
  URL
• https://{{CatalystCenter-ip}}/dna/intent/api/v1/site
  Заголовки
  — x-auth-token = {{CatalystCenter_token}}
  Пример тела запроса
  — это создаст здание с названием «Penn Plaza» в разделе «Глобальный/США»
  {
  "type": "building",
  "site": {
  "area": {
  "name": "New York",
  "parentName": "Global/United States"
  },
  «здание»: {
  «name»: «Penn Plaza»,
  "address": " 250 West 34th Street Manhattan, New York"
  }
  }
  }
  ![Screenshot 2025-09-10 at 8.41.10 PM.png]
  Пример тела запроса
  — это создаст этаж с названием «Floor_2» в «Global/United States/New York/Penn Plaza»
  {
  «type»: «floor»,
  "site": {
  "area": {
  «name»: «New York»,
  «parentName»: «Global/United States»
  },
  «здание»: {
  «name»: «Penn Plaza»,
  «адрес»: «250 West 34th Street Manhattan, New York»
  },
  «этаж» : {
  «name»: «Floor_2»,
  "parentName": "Global/United States/New York/Penn Plaza",
  «rfModel»: «Кубы и офисы с перегородками»,
  «width»: 100,
  «length»: 100,
  «height»: 10
  }
  }
  }
  ![Screenshot 2025-09-10 at 8.43.38 PM.png]
  Создание учетных данных CLI и SNMP для чтения/записи
  После создания сетевой иерархии нашей следующей задачей является создание учетных данных CLI и SNMP для чтения/записи, которые будут использоваться при обнаружении устройств. Примечание — все вызовы в этом разделе будут вызовами
  POST
  .
  URL —
  https://{{CatalystCenter-ip}}/dna/intent/api/v2/global-credential
  Заголовки —
  x-auth-token = {{CatalystCenter_token}}
  Пример тела запроса —
  это создаст учетные данные CLI с именем «admin-cli» и учетные данные SNMPv2 для чтения/записи.
  {
  "cliCredential": [
  {
  "description": "admin-cli",
  "username": "admin",
  "password": "password",
  "enablePassword": "password"
  }
  ],
  «snmpV2cRead»: [
  {
  "description": "SNMP read community
  ",
  "читающее сообщество": "public"
  }
  ],
  «snmpV2cWrite»: [
  {
  «description»: «SNMP-сообщество записи
  »,
  "writeCommunity": "private"
  }
  ]
  }
  ![Screenshot 2025-09-10 at 8.46.52 PM.png]
  Обнаружение устройств
  В предыдущем задании мы определили глобальные учетные данные для устройств. Теперь мы будем использовать эти глобальные учетные данные для обнаружения устройств, присутствующих в сети. Мы будем следовать приведенным ниже шагам, чтобы обнаружить устройства в нашей сети.
  Получение идентификатора CLI
  Первым шагом будет получение идентификатора CLI глобально настроенных учетных данных CLI, которые мы определили в предыдущем разделе. Мы будем использовать его в процессе обнаружения.
  Шаг 1.
  Используйте следующий URL-адрес запроса: https://{{CatalystCenter-ip}}/dna/intent/api/v2/global-credential и добавьте токен в раздел
  «Headers»,
  как мы делали в предыдущих задачах.
  Шаг 2. Отправьте
  запрос. В разделе «Ответ» перейдите к «cliCredentiali» и скопируйте значение ключа «id». Сохраните его в блокноте, так как мы будем использовать это значение в нашем следующем вызове POST. Аналогичным образом скопируйте значение «id» для ключей «snmpV2cRead» и «snmpV2cWrite».
  Обнаружение устройства
  URL
• https://{{CatalystCenter-ip}}/dna/intent/api/v1/discovery
  Заголовки
  – x-auth-token = {{CatalystCenter_token}}
  Пример тела запроса
  —
  добавьте идентификатор cli, который мы скопировали в предыдущем вызове API,
  и замените его в ключе «globalCredentialIdList».
  {
  "name": "discover-device-1",
  "discoveryType": "Range",
  "ipAddressList": "198.19.1.2-198.19.1.2",
  "protocolOrder": "ssh",
  "timeOut": 5,
  «retryCount»: 3,
  «globalCredentialIdList»: [
  «Добавьте здесь идентификатор CLI!», «Добавьте идентификатор snmp_read», «Добавьте идентификатор snmp_write»
  ],
  «preferredMgmtIPMethod»: «UseLoopBack»
  }
  Шаг 4 —
  Нажмите
  «Отправить».
  В разделе ответов должен появиться ответ
  202 «Принято
  ».

Проверьте, были ли обнаружены устройства
В этом разделе мы проверим, были ли обнаружены устройства. Для этого мы воспользуемся другим вызовом API, который будет вызовом GET.
Шаг 1.
Используйте следующий URL-адрес запроса: https://{{CatalystCenter-ip}}/dna/intent/api/v1/discovery/count и {{CatalystCenter-token}} в качестве токена.
Шаг 2.
Нажмите
«Отправить».
В разделе «Ответ» значение, соответствующее ключу «response», должно быть равно количеству заданий обнаружения, выполненных с помощью предыдущего вызова POST. Кроме того, для проверки в графическом интерфейсе перейдите в
«Инструменты» > «Обнаружение» > «Просмотреть все обнаружения».
![Screenshot 2025-09-10 at 8.51.28 PM.png]
Назначение устройств сайту
В последнем разделе мы обнаружили устройства, и они присутствуют в инвентаре как «Неназначенные устройства». Таким образом, нам необходимо назначить их сайтам, прежде чем мы сможем использовать возможности Catalyst Center по автоматизации и обеспечению качества.
Получите идентификатор сайта/здания/этажа, к которому будет назначено устройство
Первый шаг — получить идентификатор места, где мы собираемся назначить устройство.
Шаг 1.
Используйте следующий URL-адрес запроса: https://{{CatalystCenter-ip}}/dna/intent/api/v2/site
и добавьте токен в раздел «Заголовки».
Шаг 2 —
В разделе «Ответ» скопируйте значение ключа «id» для конкретного имени иерархии объектов и сохраните его в блокноте, чтобы использовать позже.
2.
Получите device-id устройства, которое необходимо назначить
Второй шаг — получить deviceID, то есть идентификатор устройства, которое мы пытаемся назначить сайту.
Шаг 1.
Используйте следующий URL-адрес запроса: https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-device и добавьте токен в раздел «Headers» (Заголовки).
Шаг 2.
В разделе «Ответ» скопируйте значение ключа «id» для устройства, которое необходимо назначить сайту, и сохраните его для дальнейшего использования.
3.
Присвойте устройство этажу
URL-адрес
— https://{{CatalystCenter-ip}}/dna/intent/api/v1/networkDevices/assignToSite/apply
Заголовки
— x-auth-token = {{CatalystCenter_token}}
Пример тела запроса
— добавьте значения ID сайта и ID устройства, которые мы получили в предыдущих разделах, и добавьте их в тело запроса.
{
"deviceIds": [
"string"
],
"siteId": "string"
}
Выполните вызов API, вы должны получить ответ
202 Accepted
в разделе ответа. Чтобы проверить в графическом интерфейсе Catalyst Center, перейдите в
раздел Provision > Inventory > {site},
чтобы увидеть, присутствует ли устройство.
![Screenshot 2025-09-10 at 8.55.23 PM.png]
Разверните шаблон DayN на устройстве
Мы развернем шаблон DayN на обнаруженных устройствах с помощью API шаблонов.
Найдите ID шаблона
Шаг 1.
Используйте следующий URL-адрес: https://{{CatalystCenter-ip}}/dna/intent/api/v2/template-programmer/project. Это будет запрос
GET
, используйте токен в качестве заголовка, как и для других запросов.
Шаг 2.
Вы должны получить ответ
200 OK
. В теле ответа проверьте название шаблона, скопируйте значение ключа «id» из словаря с названием шаблона — это идентификатор шаблона, который мы будем использовать для его развертывания.
Развертывание шаблона на устройстве
URL -
https://{{CatalystCenter-ip}}/dna/intent/api/v1/template-programmer/template/deploy
Заголовки
— x-auth-token = {{CatalystCenter_token}}
Пример тела запроса
— добавьте идентификатор шаблона в тело запроса ниже и выполните вызов AP.
{
"forcePushTemplate": false,
"targetInfo":[
{
"id": "198.19.1.2",
"type": "MANAGED_DEVICE_IP"
}
],
"templateId":"Добавьте здесь идентификатор шаблона!"
}
После выполнения мы получим ответ
202 Accepted
. В теле ответа скопируйте идентификатор развертывания: и сохраните его, так как он будет использоваться для проверки статуса развертывания шаблона.
Проверка статуса развертывания шаблона
Мы проверим, был ли шаблон развернут на устройстве.
Шаг 1 —
Это будет запрос
GET
. Используйте следующий URL-адрес.
https://{{CatalystCenter-ip}}/dna/intent/api/v1/template-programmer/template/deploy/status/{Deployement-Id}
Вместо Deployment-Id вставьте идентификатор развертывания, который вы сохранили из последнего вызова.
Шаг 2.
Вы должны получить сообщение
202 Accepted
. В теле ответа проверьте статус SUCCESS. Если он отсутствует, повторно отправьте запрос, чтобы проверить последний статус.
Получение данных Assurance
Здесь мы посмотрим, как использовать Assurance API для получения данных о состоянии нашей сети
Используйте следующий URL-адрес — https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-device/count, чтобы получить общее количество устройств из CatalystCenter, добавьте токен. Вы должны получить ответ 200 OK. В ответе мы увидим общее количество устройств
Используйте следующий URL-адрес — https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-health, чтобы получить данные о состоянии всех сетевых устройств.
Используйте следующий URL-адрес — https://{{CatalystCenter-ip}}/dna/intent/api/v1/client-health, чтобы получить данные о состоянии клиентов в сети.
Используйте следующий URL-адрес — https://{{CatalystCenter-ip}}/dna/intent/api/v1/issues, чтобы получить информацию о проблемах, влияющих на сеть.
![Screenshot 2025-09-10 at 9.00.23 PM.png]

[Martin L]

Спасибо за эту информацию!