表示Fortinet FortiManager JSON-RPC接口的基本组件
pyfmg的Python项目详细描述
概要
表示Fortinet FortiManager JSON-RPC接口的基本组件。这段代码基于fortinet开发人员网络（fndn）上ftntlib包中提供的fmg_jsonapi.py代码，最初由ashton turpin编写。此后，JP Forcioli以及Fortinet内部的其他几家公司对其进行了修改。现在已经对其进行了优化和修改，以利用标准的**kwargs功能，并进行了广泛的修改，以提高可伸缩性，并提供上下文管理和其他方面。
代码示例
使用FortiManager JSON-RPC的标准格式。
重要的是此包对FortiManager实例使用上下文行为，因此可以使用带的关键字。这将确保FortiManager实例在实例化时登录，并在with语句的作用域完成后注销。例如，要实例化IP地址为10.1.1.1、用户名为admin、密码为<；blank>；的FortiManager实例，用户只需键入：
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
显然不必使用上下文管理器。但是，如果未使用，则不会为调用方处理登录和注销功能。如果未使用上下文管理器，则将调用这些方法。例如：
fmg_instance = FortiManager('10.1.1.1', 'admin', '')
fmg_instance.login()
*something of importance accomplished here*
fmg_instance.logout()
继续，当一个FortiManager实例被实例化时，以下属性被配置（或者可以由用户配置）。提供的列表列出了默认值。
- debug (default False),
- use_ssl (default True),
- verify_ssl (default False),
- timeout (default 300)
例如，要实例化IP地址为10.1.1.1、用户名为admin、密码为<；blank>；、使用http而不是https的FortiManager实例，它处于调试模式，并在每次请求验证SSL证书后发出警告，超时时间为100，用户只需键入：
with FortiManager('10.1.1.1', 'admin', '', debug=True, use_ssl=False, debug=True, disable_request_warnings=False, timeout=100) as fmg_instance:
显然，如果没有使用上下文管理器，这些相同的参数将在标准调用中使用，因此：
fmg_instance = FortiManager('10.1.1.1', 'admin', '', debug=True, use_ssl=False, debug=True, disable_request_warnings=False, timeout=100)
已经提供了一个解决方案来确保可以处理工作区模式。创建fmg实例时，无论是使用上面所示的with语句还是在标准场景（上面也显示了）中，实例都会检查fmg的状态。登录时，将调用以检查状态，如果工作区模式作为除a0之外的任何内容返回，则提供工作区功能。需要对lock、commit和unlock进行标准调用，并传递给workspace manager对象以便于使用。如果调用方正在使用上下文管理器，那么工作区管理器现在将确保错误异常不会使adom处于锁定状态。workspace manager功能将而不是调用automaticcommit，它将简单地确保在任何锁定的adom上调用unlock\u adom函数，然后将注销。这种情况发生在注销中，因此调用者可以锁定一个ADOM（或多个ADOM），完成他的工作，在他想提交的任何ADOM上调用提交，然后简单地调用注销，然后工作区管理器将负责解锁。添加address对象的一个常见示例（使用显式调用unlock\u adom）可能是：
fmg_instance.lock_adom("root")
fmg_instance.add('pm/config/adom/{adom}/obj/firewall/address'.format(adom="root"), allow__routing=0, associated__interface='any', name='add_obj_name', subnet=["192.168.1.0", "255.255.255.0"], type=0, comment='API address obj addition')
fmg_instance.commit_changes("root")
fmg_instance.unlock_adom("root")
fmg_instance.logout()
下面将执行相同的操作，并在退出时解锁rootadom（请注意，此处不需要调用unlock\u adom）：
fmg_instance.lock_adom("root")
fmg_instance.add('pm/config/adom/{adom}/obj/firewall/address'.format(adom="root"), allow__routing=0, associated__interface='any', name='add_obj_name', subnet=["192.168.1.0", "255.255.255.0"], type=0, comment='API address obj addition')
fmg_instance.commit_changes("root")
fmg_instance.logout()
虽然这个模块应该与另一个调用方编写的抽象一起使用，但是没有理由这个模块不能被自己用来进行详细的、多参数的调用。为此，我们提供了一种功能，可以将关键字/值参数传递到任何get，add，update，delete，set，替换，克隆，执行，或移动帮助程序方法。由于FortiManager正文中有许多关键字需要破折号（并且由于破折号字符不允许作为由**Kwargs指针处理的关键字参数），因此添加了一个功能，使得带有双下划线的关键字是自动的。当关键字/值对放入调用主体时，ly转换为破折号。下面是一个示例（请注意关键字项中的双下划线，当调用时，它们将转换为破折号）：
fmg_instance.add('pm/config/adom/{adom}/obj/firewall/address'.format(adom="root"), allow__routing=0, associated__interface='any', name='add_obj_name', subnet=["192.168.1.0", "255.255.255.0"], type=0, comment='API address obj addition')
这一概念的另一个补充是，FortiManager需要一个两个单词之间有空格的属性。由于这是不允许的，因此添加了一个功能，当关键字/值对放入调用主体时，带有三重下划线的关键字会自动转换为空白。下面是一个示例（注意关键字项中的三个下划线，在调用时它们将转换为空格）：
fmg_instance.add('pm/config/adom/{adom}/obj/firewall/address'.format(adom="root"), fake___attribute='any', name='add_obj_name', subnet=["192.168.1.0", "255.255.255.0"], type=0, comment='API address obj addition')
这些工具是有用的，但是下面的测试部分显示了一种更明显的方法，可以更清晰地进行此类调用，其中有效地使用了标准字典。在这种情况下，不需要双下划线翻译，破折号可以很好地工作（见下文）。使用自由形式方法时，属性中的空格也是如此。
例外情况
该模块提供以下例外情况以供使用：
- fmgbaseexception（异常）
- fmgValidSessionException（fmgbaseeException）
- fmgvalueerror（valueerror）
- fmgresponsenotformedcorrect（键错误）
- fmgconnectionerror（reqconnerror）
- fmgconnecttimeout（reqconnttimeout）
- fmgrequestnotformedcorrect（fmgbaseexception） < > >
fmgbaseexception是模块的基本异常，可用于捕获valueerror和keyerror问题之外的所有内容。
然后，调用方可以编写以下内容，并拥有与标准的调用等效的调用，除了不提及异常的调用。这确保了可扩展性：
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
fmgValidSessionException已添加，如果在未与fmg建立有效连接的情况下尝试任何调用，则会引发该异常。在过去，除了在登录返回后检查对象的_u str（）uuu值之外，尽管没有有效的会话，代码仍会继续尝试进行调用。现在在无效会话上尝试的任何调用都将引发此错误。
fmgvalueerror是标准值错误，在进行连接尝试或使用无效值进行调用的特殊情况下会被捕获。例如，连接到fmg实例时，超时值为<；=0。
当从fmg实例接收到的响应没有结果、状态或代码属性时，将引发fmgresponsenotformedcorrect。没有这些属性的fmg响应是格式错误的，并将引发此错误。唯一的例外是来自有效login（）调用的响应。此异常将被抑制，并为登录创建有效的响应，以确保从模块返回稳定、标准和恒定的响应。
fmgconnectionerror和fmgconnecttimeout在捕获到请求。异常。connectionerror或请求。异常。connecttimeout异常时引发。这确保调用代码不需要导入/依赖请求模块来处理请求连接异常。fmgconnectionerror最有可能在login（）处引发，原因可能是fmg设备的主机名或IP地址不正确。
fmgrequestnotformedcorrect。具体来说，需要传入一个data关键字，并且该值必须是字典。参见下面的 异常被允许向调用方提出，并且只在某些情况下被捕获，在要求详细模式并且调用方希望打印出异常时需要这些异常。打印完成后，将引发并提出相同的异常，以便调用方可以捕获和处理该异常，或将其用作调试工具。 本节概述了**kwargs中使用的特殊关键字，这些关键字对pyfmg有重要意义。当呼叫者使用这些关键字时，将进行检查，并为PyFMG呼叫提供特殊情况，因为在与FortiManager打交道时有许多特殊要求。 data关键字-在请求对象的params部分使用数组而不是json对象。 当需要一个对象数组时，这种情况是必需的，而json对象可能包含数组或其他对象。例如，需要如下所示的请求： 请注意，params属性包含一个data属性，该属性是一个项数组，而不是通常所需的标准json对象。要利用此功能，调用方将在调用中提供一个关键字data，并将信息数组作为其值。通话内容如下： 超过数据关键字的所有关键字都将被忽略。 这个模块提供了一个标准的响应机制，以便调用对象知道要返回什么。除非抛出异常，否则此模块将返回一个2对象元组，该元组由返回的响应代码组成，后跟响应中的"data"属性中的信息。如果响应中没有数据属性，则提供响应的文本。由于登录不提供来自fmg设备的恒定响应，因此此模块提供一个响应，以确保调用方知道将返回什么以及以什么格式返回。登录、get call和注销过程的响应示例如下： 注意登录响应（上面的第一个响应）不是unicode。除此之外，它与其他呼叫响应完全匹配。 当一个操作被发送到fmg，作为返回启动系统上的一个任务（即设备配置安装、策略包推送等）时，返回值如所讨论的，其中提供了一个带有返回代码和返回json值的元组。在这种情况下，json值将有一个task identifier属性，可用于跟踪该任务。此模块提供一个简单的跟踪任务处理功能，称为track\u task（），它接受一个task\u id整数，然后接受请求之间的睡眠时间（默认值为5秒）、检索失败门（默认值为10）和超时（默认值为10是120）。这为该任务提供了一个循环响应，默认情况下，该响应允许系统花费大约一分钟的时间来响应-该值是一个很长的时间，因此我们可以确定，如果系统到那时没有响应，则会出现问题。循环每5秒向系统请求一次有关任务的信息，并在系统给出任务花费太长时间的响应之前给系统2分钟以上的时间来完成。此函数允许获取任务，然后观察值，以及从fmg响应的富数据中旋转，以包括已完成的行数、任何错误或警告、完成时间等。系统还为完成周期的响应数据添加一个名为total_task的属性_ time任务完成其操作所用的时间。调用和使用此函数的方法如下： 添加了标准get，add，update，delete，set，replace，clone，execute或move之外的执行函数。此函数称为 此软件包的建立是为了支持可靠的需求和适当的模型利用率，但是，它可以用于与任何Fortinet FortiManager设备或虚拟机资产的联系。 将通过PIP接口安装此软件包 使用库相对简单。 假设您在WITH上下文中，仍然像以前一样使用fmg_实例，要在根目录ADOM中获取所有受管设备，将使用以下命令： 要添加地址组，请使用以下命令： 注意如何创建数据字典，然后作为**数据发送。这是因为字典的键中存在必需的破折号，而关键字参数设置中不允许使用破折号。例如，假设此调用不需要允许路由和关联接口。在这种情况下，电话可能是： 请注意，您只需将需要发送到FortiManager设备的数据发送到**Kwargs字段-这使得调用非常简单-发送一个URL和关键字参数，其余的都会得到处理。 欢迎加入QQ群-->： 979659372
free_form（）方法说明
特殊关键字
1
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
2
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
响应
3
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
特殊功能
4
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
自由形式（方法，**kwargs）。参数是必须调用的字符串方法，例如add或get等。还有一个关键字参数列表。kw参数必须是具有键data的字典，否则将引发fmgrequestnotformedcorrect异常。此数据关键字必须具有要发送到fmg的确切值。此函数用于fmg请求对象与标准对象稍有不同，或者您试图通过多个操作调用fmg时。例如，您想用一个调用添加3个地址对象。为了执行类似的操作，使用并调用free_form（）函数，如下所示，我们使用一个调用从策略ID的1、3、4、5和7请求所有数据：
5
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
动机
安装
测试
6
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
7
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
8
with FortiManager('10.1.1.1', 'admin', '') as fmg_instance:
推荐PyPI第三方库