netapp.ontap.na_ontap_restit 模块 – NetApp ONTAP 在 ONTAP 上运行任何 REST API
注意
此模块是 netapp.ontap 集合 (版本 22.13.0) 的一部分。
如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install netapp.ontap。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。
要在 playbook 中使用它，请指定：netapp.ontap.na_ontap_restit。
netapp.ontap 20.4.0 中的新增功能
概要
在 ONTAP 上调用 REST API。
集群 REST API 使用集群管理员帐户运行。
Vserver REST API 可以使用 vsadmin 帐户或使用 vserver 隧道 (具有 *vserver_* 选项的集群管理员) 运行。
成功的情况下，将返回一个 json 字典作为
response。如果发生 REST API 错误，则设置
status_code、error_code、error_message来帮助诊断问题，并将调用报告为错误（“失败”）。
其他错误（例如连接问题）将报告为 Ansible 错误。
要求
执行此模块的主机需要以下要求。
Ansible 2.9 或更高版本 - 建议使用 2.12 或更高版本。
Python3 - 建议使用 3.9 或更高版本。
使用 ZAPI 时，需要 netapp-lib 2018.11.13 或更高版本（使用“pip install netapp-lib”安装），强烈建议使用 netapp-lib 2020.3.12，因为它提供了更好的连接问题错误报告。
物理或虚拟集群式 Data ONTAP 系统，模块支持 Data ONTAP 9.1 及更高版本，REST 支持需要 ONTAP 9.6 或更高版本。
参数
参数 |
注释 |
|---|---|
Accept 请求 HTTP 标头的值。 这很少需要，但需要读取文件（参见示例）。 对于大多数情况，省略此字段。当期望此格式时，将其设置为“multipart/form-data”。 默认情况下，当 hal_linking 为 true 时，模块使用“application/json”或“application/hal+json”。 |
|
要调用的 REST API（例如 *cluster/software*、*svms/svm*）。 |
|
info 参数的字典 |
|
SSL 客户端证书文件（.pem）的路径。 python 2.6 不支持。 |
|
启用或禁用新功能。 这可以用来启用实验性功能或禁用破坏向后兼容性的新功能。 支持的键和值可能会随时更改，恕不另行通知。未知键将被忽略。 |
|
使用 multipart/form-data 时参数的字典。 这很少需要，但需要写入文件（参见示例） 如果存在，请求将自动将 Content-Type 标头设置为 multipart/form-data。 |
|
使用 REST 时覆盖集群 ONTAP 版本。 如果版本与目标集群不匹配，则行为未定义。 这是在由于权限问题无法读取集群版本时提供的解决方法。请参阅 https://github.com/ansible-collections/netapp.ontap/wiki/Known-issues。 这应该是 9.10 或 9.10.1 的形式，每个元素都是整数。 |
|
如果为 true，则在响应中返回 HAL 编码的链接。 选项
|
|
ONTAP 实例的主机名或 IP 地址。 |
|
使用此端口覆盖默认端口 (80 或 443) |
|
启用和禁用 https。 使用 REST 时被忽略，因为只支持 https。 使用 SSL 证书身份验证时被忽略，因为它需要 SSL。 选项
|
|
SSL 客户端密钥文件的路径。 |
|
要使用的 REST 方法。 默认值： |
|
指定用户的密码。 |
|
查询参数的字典列表 |
|
此模块仅支持 REST。 always – 将始终使用 REST API。如果模块不支持 REST，则会发出警告。 默认值： |
|
这可以是集群范围或 SVM 范围的帐户，具体取决于是否需要集群级或 SVM 级 API。 更多信息，请阅读文档 https://mysupport.netapp.com/NOW/download/software/nmsdk/9.4/。 支持两种身份验证方法
要使用证书，必须已在 ONTAP 集群中安装该证书，并且必须已启用证书身份验证。 |
|
如果设置为 仅当在使用自签名证书的个人控制站点上使用时，才应将其设置为 选项
|
|
如果提供，则强制使用 vserver 隧道。用户名标识集群管理员帐户。 |
|
如果提供，则强制使用 vserver 隧道。用户名标识集群管理员帐户。 |
|
当为 true 时，POST/PATCH/DELETE 可以同步和异步处理。 如果响应指示作业正在进行中，则会定期检查作业状态，直到作业完成。 当为 false 时，调用会立即返回。 选项
|
备注
注意
以 na_ontap 为前缀的模块构建为支持 ONTAP 存储平台。
默认情况下启用 https，建议使用。要在集群上启用 http，必须运行以下命令“set -privilege advanced;”“system services web modify -http-enabled true;”。
示例
-
name: Ontap REST API
hosts: localhost
gather_facts: False
collections:
- netapp.ontap
vars:
login: &login
hostname: "{{ admin_ip }}"
username: "{{ admin_username }}"
password: "{{ admin_password }}"
https: true
validate_certs: false
svm_login: &svm_login
hostname: "{{ svm_admin_ip }}"
username: "{{ svm_admin_username }}"
password: "{{ svm_admin_password }}"
https: true
validate_certs: false
tasks:
- name: run ontap REST API command as cluster admin
na_ontap_restit:
<<: *login
api: cluster/software
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- name: run ontap REST API command as cluster admin
na_ontap_restit:
<<: *login
api: cluster/software
query:
fields: version
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- name: run ontap REST API command as cluster admin
na_ontap_restit:
<<: *login
api: svm/svms
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- name: run ontap REST API command as cluster admin
na_ontap_restit:
<<: *login
api: svm/svms
query:
fields: aggregates,cifs,nfs,uuid
query_fields: name
query: trident_svm
hal_linking: true
register: result
- debug: var=result
- name: run ontap REST API command as vsadmin
na_ontap_restit:
<<: *svm_login
api: svm/svms
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- name: run ontap REST API command as vserver tunneling
na_ontap_restit:
<<: *login
api: storage/volumes
vserver_name: ansibleSVM
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- set_fact:
uuid: "{{ result.response.records | json_query(get_uuid) }}"
vars:
get_uuid: "[? name=='deleteme_ln1'].uuid"
- debug: var=uuid
- name: run ontap REST API command as DELETE method with vserver tunneling
na_ontap_restit:
<<: *login
api: "storage/volumes/{{ uuid[0] }}"
method: DELETE
vserver_name: ansibleSVM
query:
return_timeout: 60
register: result
when: uuid|length == 1
- debug: var=result
- assert: { that: result.skipped|default(false) or result.status_code|default(404) == 200, quiet: True }
- name: run ontap REST API command as POST method with vserver tunneling
na_ontap_restit:
<<: *login
api: storage/volumes
method: POST
vserver_name: ansibleSVM
query:
return_records: "true"
return_timeout: 60
body:
name: deleteme_ln1
aggregates:
- name: aggr1
register: result
- debug: var=result
- assert: { that: result.status_code==201, quiet: True }
- name: run ontap REST API command as DELETE method with vserver tunneling
# delete test volume if present
na_ontap_restit:
<<: *login
api: "storage/volumes/{{ result.response.records[0].uuid }}"
method: DELETE
vserver_name: ansibleSVM
query:
return_timeout: 60
register: result
- debug: var=result
- assert: { that: result.status_code==200, quiet: True }
- name: create a file
# assuming credentials are set using module_defaults
na_ontap_restit:
api: storage/volumes/f3c003cb-2974-11ed-b2f8-005056b38dae/files/laurent123.txt
method: post
files: {'data': 'some data'}
- name: read a file
# assuming credentials are set using module_defaults
na_ontap_restit:
api: storage/volumes/f3c003cb-2974-11ed-b2f8-005056b38dae/files/laurent123.txt
method: get
accept_header: "multipart/form-data"
query:
length: 100
# error cases
- name: run ontap REST API command
na_ontap_restit:
<<: *login
api: unknown/endpoint
register: result
ignore_errors: True
- debug: var=result
- assert: { that: result.status_code==404, quiet: True }
返回值
常用返回值已在 此处 记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
如果执行了 REST API 但失败，则为 REST API 设置的错误代码。 如果成功或无法执行 REST API 调用，则不会出现。 返回：出错时 |
|
如果执行了 REST API 但失败，则为 REST API 设置的错误消息。 如果成功或无法执行 REST API 调用，则不会出现。 返回：出错时 |
|
如果成功，则为 REST API 返回的 json 字典。 如果执行了 REST API 但失败，则为空字典。 如果无法执行 REST API 调用，则不会出现。 返回：成功时 |
|
http 状态代码。 当 wait_for_completion 为 True 时，这将强制设置为 0。 返回：始终 |