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以帮助诊断问题，并将调用报告为错误（“failed”）。
其他错误（例如连接问题）将报告为 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。 返回: 总是 |