ansible#shell技术杂谈

Netbox-api使用讲解

2023年8月18日
0

什么是 REST API？

REST 代表 具象状态转移。它是一种特殊类型的API，它使用HTTP请求和JavaScript对象表示法（JSON）来促进对应用程序中对象的创建，检索，更新和删除（CRUD）操作。每种类型的操作都与特定的 HTTP 谓词相关联：

  • GET：检索对象或对象列表
  • POST：创建对象
  • PUT / PATCH：修改现有对象。 要求指定所有必填字段，而仅要求指定正在修改的字段。PUTPATCH
  • DELETE：删除现有对象

REST API 的主要优点之一是它的人性化。因为它利用HTTP和JSON，所以使用常用工具在命令行上与NetBox数据进行交互非常容易。例如，我们可以从 NetBox 请求一个 IP 地址，并使用 和 输出 JSON。以下命令发出 HTTP 请求，以获取有关特定 IP 地址的信息（由其主键标识），并用于以更人性化的格式呈现返回的原始 JSON 数据。（通过管道传输输出不是严格要求的，但使其更易于阅读。

curl -s http://netbox/api/ipam/ip-addresses/2954/ | jq '.'
{
  "id": 2954,
  "url": "http://netbox/api/ipam/ip-addresses/2954/",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "address": "192.168.0.42/26",
  "vrf": null,
  "tenant": null,
  "status": {
    "value": "active",
    "label": "Active"
  },
  "role": null,
  "assigned_object_type": "dcim.interface",
  "assigned_object_id": 114771,
  "assigned_object": {
    "id": 114771,
    "url": "http://netbox/api/dcim/interfaces/114771/",
    "device": {
      "id": 2230,
      "url": "http://netbox/api/dcim/devices/2230/",
      "name": "router1",
      "display_name": "router1"
    },
    "name": "et-0/1/2",
    "cable": null,
    "connection_status": null
  },
  "nat_inside": null,
  "nat_outside": null,
  "dns_name": "",
  "description": "Example IP address",
  "tags": [],
  "custom_fields": {},
  "created": "2020-08-04",
  "last_updated": "2020-08-04T14:12:39.666885Z"
}

IP 地址的每个属性都表示为 JSON 对象的一个属性。字段可能包含自己的嵌套对象，如上述字段的情况。每个对象都包含一个主键，该主键在数据库中唯一标识它。assigned_objectid

交互式文档

所有 REST API 端点的全面交互式文档可在正在运行的 NetBox 实例上找到，网址为 。此接口提供了一个方便的沙盒，用于研究和试验特定终结点和请求类型。还可以使用 Web 浏览器浏览 API 本身，方法是导航到其根目录。/api/schema/swagger-ui//api/

端点层次结构

NetBox 的整个 REST API 都位于 API 根目录下。URL 结构按应用程序在根级别划分：电路、DCIM、附加、IPAM、插件、租户、用户和虚拟化。每个应用程序中每个模型都有一个单独的路径。例如，提供程序和电路对象位于“电路”应用程序下：https://<hostname>/api/

  • /api/circuits/providers/
  • /api/circuits/circuits/

同样，站点、机架和设备对象位于“DCIM”应用程序下：

  • /api/dcim/sites/
  • /api/dcim/racks/
  • /api/dcim/devices/

可以通过在 Web 浏览器中导航到 API 根来查看可用终结点的完整层次结构。

每个模型通常有两个与之关联的视图：列表视图和详细信息视图。列表视图用于检索包含多个对象的列表并创建新对象。详细信息视图用于检索、更新或删除单个现有对象。所有对象都由其数字主键 （） 引用。id

  • /api/dcim/devices/– 列出现有设备或创建新设备
  • /api/dcim/devices/123/– 检索、更新或删除 ID 为 123 的设备

可以使用一组查询参数筛选对象列表。例如，要查找属于 ID 为 123 的设备的所有接口，请执行以下操作：

GET /api/dcim/interfaces/?device_id=123

通用关系

NetBox 中的某些对象具有可以引用多种类型的对象的属性，称为泛型关系。例如，可以将 IP 地址分配给设备接口或虚拟机接口。通过 REST API 进行此分配时，我们必须指定两个属性：

  • assigned_object_type– 分配对象的内容类型，定义为<app>.<model>
  • assigned_object_id– 分配对象的唯一数字 ID

这些值共同标识 NetBox 中的唯一对象。分配的对象（如果有）由 IP 地址模型上的属性表示。assigned_object

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox/api/ipam/ip-addresses/ \
--data '{
    "address": "192.0.2.1/24",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 69023
}'

{
    "id": 56296,
    "url": "http://netbox/api/ipam/ip-addresses/56296/",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 69000,
    "assigned_object": {
        "id": 69000,
        "url": "http://netbox/api/dcim/interfaces/69023/",
        "device": {
            "id": 2174,
            "url": "http://netbox/api/dcim/devices/2174/",
            "name": "device105",
            "display_name": "device105"
        },
        "name": "ge-0/0/0",
        "cable": null,
        "connection_status": null
    },
    ...
}

更新对象

要修改已创建的对象，请向模型的详细信息端点发出请求，指定其唯一的数字 ID。 包括您希望在对象上更新的任何数据。与对象创建一样，还必须指定 和 标头。PATCHAuthorizationContent-Type

curl -s -X PATCH \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/ipam/prefixes/18691/ \
--data '{"status": "reserved"}' | jq '.'
{
  "id": 18691,
  "url": "http://netbox/api/ipam/prefixes/18691/",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "prefix": "192.0.2.0/24",
  "site": {
    "id": 6,
    "url": "http://netbox/api/dcim/sites/6/",
    "name": "US-East 4",
    "slug": "us-east-4"
  },
  "vrf": null,
  "tenant": null,
  "vlan": null,
  "status": {
    "value": "reserved",
    "label": "Reserved"
  },
  "role": null,
  "is_pool": false,
  "description": "",
  "tags": [],
  "custom_fields": {},
  "created": "2020-08-04",
  "last_updated": "2020-08-04T20:14:55.709430Z"
}

更新多个对象

通过向模型的列表端点发出 or 请求，可以同时更新多个对象，该词典列表指定要删除的每个对象的数字 ID 和要更新的属性。例如，要将 ID 为 10 和 11 的网站更新为“活动”状态，请发出以下请求：PUTPATCH

curl -s -X PATCH \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/dcim/sites/ \
--data '[{"id": 10, "status": "active"}, {"id": 11, "status": "active"}]'

请注意，不要求对象之间的属性相同。例如，可以在同一请求中更新一个站点的状态以及另一个站点的名称。

删除对象若要从 NetBox 中删除对象，请向模型的详细信息终结点发出请求，指定其唯一的数字 ID。必须包含标头才能指定授权令牌，但是此类请求不支持在正文中传递任何数据。

DELETEAuthorization

curl -s -X DELETE \
-H "Authorization: Token $TOKEN" \
http://netbox/api/ipam/prefixes/18691/

适用于ansible-awx示例

---
- name: Import host information to NetBox
  hosts: all
  gather_facts: true

  tasks:
    - name: Gather host facts
      setup:

    - name: Generate JSON payload
      set_fact:
        netbox_payload:
          name: "{{ ansible_hostname }}"
          device_type: "{{ device_type }}"
          device_role: "{{ device_role }}"
          site: "{{ site }}"
          # Add more fields as per your requirements

    - name: Export JSON payload to a file
      copy:
        content: "{{ netbox_payload | to_nice_json }}"
        dest: /tmp/netbox_payload.json

    - name: Import host information to NetBox
      shell: 'curl -s -X POST -H "Authorization: Token {{ token }}" -H "Content-Type: application/json" -d @/tmp/netbox_payload.json "{{ api_url }}"'
      register: curl_output
      changed_when: false

    - name: Display curl command output
      debug:
        var: curl_output.stdout_lines

这个playbook 主要获取主机基础信息 使用的 CURL 命令用于将生成的 JSON 数据通过 POST 请求发送到 NetBox 的 API。让我们来解释每个部分的含义：

  • -s: 静默模式，不显示进度和错误信息。
  • -X POST: 发送一个 HTTP POST 请求。
  • -H "Authorization: Token {{ token }}": 添加一个 HTTP 头部，用于身份验证。{{ token }} 是一个变量，应该被替换为实际的令牌值。
  • -H "Content-Type: application/json": 添加一个 HTTP 头部，指定请求的内容类型为 JSON。
  • -d @/tmp/netbox_payload.json: 使用 -d 参数指定要发送的数据，@/tmp/netbox_payload.json 表示从指定文件中读取 JSON 数据。
  • "{{ api_url }}": 这是请求的目标 URL，{{ api_url }} 是一个变量，应该被替换为实际的 API 终端点地址。

如果你将这个 CURL 命令放入 Shell 脚本中，确保替换所有的变量（如 {{ token }} 和 {{ api_url }}）为实际的值。这样就能够通过 API 请求将 JSON 数据发送到 NetBox 并完成相应的操作。

---
- name: Import host information to NetBox
  hosts: all
  gather_facts: true
  
  tasks:
   - name: Gather host facts
     setup:

   - name: Generate JSON payload
     set_fact:
       interface_payload:
         device: "{{ ansible_hostname }}"
         name: "DefaultInterface"
         type: other

   - name: Create JSON payload
     copy:
       content: "{{ interface_payload | to_nice_json }}"
       dest: /tmp/interface.json

   - name: Post data to NetBox
     shell: 'curl -s -X POST -H "Authorization: Token {{ token }}" -H "Content-Type: application/json" -d @/tmp/interface.json "{{ api_url }}"/api/dcim/interfaces/'

获取接口信息
Prev Next
No Comments

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注