openwisp-ipam 1.0

运行测试

安装测试需求

pip install -r requirements-test.txt

然后运行测试套件

# options "--keepdb" & "--parallel" are optional but
# improve time required for running tests.
./runtests.py --keepdb --parallel
# Run tests for the sample_app
SAMPLE_APP=1 ./runtests.py --keepdb --parallel

实时文档

一个通用的实时 API 文档（遵循 OpenAPI 规范）可在 /api/v1/docs/ 获得。

可浏览的Web界面

此外，在浏览器中直接打开以下任何端点 列出，将显示 Django-REST-Framework 可浏览的 API 界面，这使得查找每个端点的详细信息变得更加容易。

身份验证

请参阅 openwisp-users: 使用用户令牌进行认证。

当通过 实时文档 或 可浏览的网页 浏览 API 时，您还可以使用会话认证通过 django admin 登录。

分页

所有 list 端点支持 page_size 参数，允许与 page 参数结合分页结果。

GET /api/v1/<api endpoint url>/?page_size=10
GET /api/v1/<api endpoint url>/?page_size=10&page=2

端点列表

由于详细说明包含在每个端点的 实时文档 和 可浏览网页 中，因此这里我们只提供可用的端点列表，有关更多信息，请打开浏览器中的端点 URL。

API节流

要覆盖默认 API 速率限制设置，请将以下内容添加到您的 settings.py 文件中

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_RATES': {
        'ipam': '100/hour',
    }
}

DEFAULT_THROTTLE_RATES 中使用的速率描述可能包括 second、minute、hour 或 day 作为速率限制周期。

获取下一个可用的IP

一个模型方法，用于获取特定子网下的下一个可用的 IP 地址。此方法也可以通过 REST API 访问：openwisp_ipam/base/models.py

/api/v1/ipam/subnet/<subnet_id>/get-next-available-ip/

POST /api/v1/ipam/subnet/<subnet_id>/request-ip/

{
    "ip_address": "ip_address",
    "subnet": "subnet_uuid",
    "description": "optional description"
}

IpAddress-Subnet 列表和创建视图

一个API端点，用于检索或创建特定子网下的IP地址。

/api/v1/ipam/subnet/<subnet_id>/ip-address/

/api/v1/ipam/subnet/<subnet_id>/ip-address/

子网列表/创建视图

一个API端点，用于创建或检索子网实例的列表。

/api/v1/ipam/subnet/

/api/v1/ipam/subnet/

子网视图

一个API端点，用于检索、更新或删除子网实例。

/api/v1/ipam/subnet/<subnet-id>/

/api/v1/ipam/subnet/<subnet-id>/

/api/v1/ipam/subnet/<subnet-id>/

IP地址视图

一个API端点，用于检索、更新或删除IP地址实例。

/api/v1/ipam/ip-address/<ip_address-id>/

/api/v1/ipam/ip-address/<ip_address-id>/

/api/v1/ipam/ip-address/<ip_address-id>/

导出子网视图

用于导出子网数据的视图。

/api/v1/ipam/subnet/<subnet-id>/export/

导入子网视图

用于导入子网数据的视图。

/api/v1/ipam/import-subnet/

导出和导入子网

用户可以使用openwisp-ipam轻松导入和导出子网数据及其IP地址。这适用于IPv4和IPv6类型的网络。

导出

可以通过管理界面或使用管理命令导出数据。导出的数据以.csv文件格式。

从管理命令

./manage.py export_subnet <subnet value>

如果数据库中存在子网，则导出子网。

从管理界面

可以通过在子网的管理更改视图中单击导出按钮从管理界面导出数据。

导入

可以通过管理界面或使用管理命令导入数据。导入的数据文件可以是.csv和.xlsx格式。在导入IP地址数据时，系统会检查导入文件中指定的子网是否存在。如果子网不存在，则会在导入数据时创建。

从管理命令

./manage.py import_subnet --file=<file path>

从管理界面

可以通过在子网视图中单击导入按钮从管理界面导入数据。

CSV文件格式

在创建导入数据时，请遵循以下结构。

Subnet Name
Subnet Value
Organization Slug

ip_address,description
<ip-address>,<optional-description>
<ip-address>,<optional-description>
<ip-address>,<optional-description>

1. 初始化您的自定义模块

首先，您需要创建一个新的 Django 应用，这个应用将包含您自定义的 openwisp-ipam 版本。

Django 应用实际上就是一个 Python 包（Python 脚本目录），在下面的示例中，我们将这个 Django 应用命名为 myipam，但您可以取任何您想要的名称。

django-admin startapp myipam

请记住，上述命令必须从您的 PYTHON_PATH 目录中调用，这样您就可以将结果导入到您的项目中。

现在，您需要将 myipam 添加到您的 settings.py 文件中的 INSTALLED_APPS，同时确保已经移除了 openwisp_ipam。

INSTALLED_APPS = [
    # ... other apps ...
    'openwisp_utils.admin_theme',
    # all-auth
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    # openwisp2 modules
    'openwisp_users',
    # 'myipam',   <-- replace without your app-name here
    # admin
    'django.contrib.admin',
    # rest framework
    'rest_framework',
    # Other dependencies
    'reversion',
]

有关如何使用 Django 项目和 Django 应用的更多信息，请参阅 Django 文档。

2. 安装 openwisp-ipam

安装（并将 openwisp-ipam 添加到您的项目需求中）

pip install openwisp-ipam

3. 添加 EXTENDED_APPS

将以下内容添加到您的 settings.py

EXTENDED_APPS = ('openwisp_ipam',)

4. 添加 openwisp_utils.staticfiles.DependencyFinder

将 openwisp_utils.staticfiles.DependencyFinder 添加到您的 settings.py 中的 STATICFILES_FINDERS

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

5. 添加 openwisp_utils.loaders.DependencyLoader

将 openwisp_utils.loaders.DependencyLoader 添加到您的 settings.py 中的 TEMPLATES，但请确保它位于 django.template.loaders.app_directories.Loader 之前。

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'openwisp_utils.loaders.DependencyLoader',
                'django.template.loaders.app_directories.Loader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

6. 继承 AppConfig 类

请参考测试项目的示例应用中的以下文件

• sample_ipam/__init__.py.

• sample_ipam/apps.py.

您需要在您的项目中复制并适配这段代码。

有关 AppConfig 概念的更多信息，请参阅 Django 文档中的“Applications”部分。

7. 创建自定义模型

为了举例说明，我们在测试项目的示例应用的 模型中添加了一个简单的“详细信息”字段。

您可以通过类似的方式在您的 models.py 文件中添加字段。

注意：有关如何使用、扩展或开发模型的问题，请参阅 Django 文档中的“Models”部分。

8. 添加交换配置

创建模型后，将以下内容添加到您的 settings.py

# Setting models for swapper module
OPENWISP_IPAM_IPADDRESS_MODEL = 'myipam.IpAddress'
OPENWISP_IPAM_SUBNET_MODEL = 'myipam.Subnet'

将 myipam 替换为步骤 1 中您选择的名称。

9. 创建数据库迁移

创建并应用数据库迁移

./manage.py makemigrations
./manage.py migrate

有关更多信息，请参阅 Django 文档中的“Migrations”部分。

10. 创建管理员界面

参考示例应用的 admin.py 文件。

要修改 admin，您主要有以下两种方式，如下所述。

注意：有关 Django admin 的工作方式或如何进行自定义的更多信息，请参阅 Django 文档中的“Django admin site”部分。

from openwisp_ipam.admin import IpAddressAdmin, SubnetAdmin

SubnetAdmin.app_label = 'sample_ipam'

from django.contrib import admin
from openwisp_ipam.admin import (
    IpAddressAdmin as BaseIpAddressAdmin,
    SubnetAdmin as BaseSubnetAdmin,
)
from swapper import load_model

IpAddress = load_model('openwisp_ipam', 'IpAddress')
Subnet = load_model('openwisp_ipam', 'Subnet')

admin.site.unregister(IpAddress)
admin.site.unregister(Subnet)

@admin.register(IpAddress)
class IpAddressAdmin(BaseIpAddressAdmin):
    # add your changes here

@admin.register(Subnet)
class SubnetAdmin(BaseSubnetAdmin):
    app_label = 'myipam'
    # add your changes here

11. 创建根 URL 配置

from .sample_ipam import views as api_views
from openwisp_ipam.urls import get_urls

urlpatterns = [
    # ... other urls in your project ...
    # openwisp-ipam urls
    # path('', include(get_urls(api_views))) <-- Use only when changing API views (dicussed below)
    path('', include('openwisp_ipam.urls')),
]

有关 Django 中 URL 配置的更多信息，请参阅 Django 文档中的“URL dispatcher”部分。

12. 导入自动化测试

在基于本模块开发自定义应用程序时，建议同时导入并运行基本测试，以确保您引入的更改不会破坏openwisp-ipam的一些现有功能。

如果您需要添加破坏性更改，可以覆盖基类中定义的测试来测试自己的行为。

有关如何进行此操作的示例，请参阅示例应用程序的测试。

您可以使用以下命令运行测试：

# the --parallel flag is optional
./manage.py test --parallel myipam

将 myipam 替换为步骤 1 中您选择的名称。

有关Django中自动化测试的更多信息，请参阅“Django中的测试”。

其他可继承和扩展的基类

以下步骤不是必需的，仅供更高级的自定义使用。