第 3 章 API 语法
您可以查看 API 请求和 JSON 响应的基本语法。
虽然 Satellite 6 API 版本 1 和 2 可用，但红帽只支持版本 2。
3.1. API 请求组成
内置 API 引用显示 API 路由或路径，前面带有 HTTP 方法：
HTTP_METHOD API_ROUTE
要使用 API，请使用 curl 命令语法和参考文档中的 API 路由来构造命令：
$ curl --request HTTP_METHOD \ 1 --insecure \ 2 --user My_User_Name:My_Password \ 3 --data @input_file.json \ 4 --header "Accept:application/json" \ 5 --header "Content-Type:application/json" \ 6 --output output_file 7 API_ROUTE \ 8 | python3 -m json.tool 9
- 1
- 要将
curl用于 API 调用，请使用 the-request选项指定 HTTP 方法。例如，--request POST。 - 2
- 添加
-insecure选项以跳过 SSL 对等证书验证检查。红帽建议您配置 SSL 身份验证并使用安全调用。如需更多信息，请参阅 第 4.1 节 “SSL 身份验证概述”。 - 3
- 通过 -user 选项提供 Satellite 用户凭据。
- 4
- 5 6
- 7
- 从 Satellite 服务器下载内容时，请使用--
output 选项指定输出文件。 - 8
- 使用以下格式的 API 路由：
https://satellite.example.com/katello/api/activation_keys。在 Satellite 6 中，API 的版本 2 是默认值。因此，在 API 调用的 URL 中使用v2不需要。 - 9
- 将输出重定向到 Python
json.tool模块，以便更轻松地读取输出。
3.1.1. 使用 GET HTTP 方法
使用 GET HTTP 方法从 API 中获取有关现有条目或资源的数据。
Example
这个示例请求 Satellite 主机的数量：
请求示例：
$ curl --request GET --user My_User_Name:My_Password \ https://satellite.example.com/api/hosts | python3 -m json.tool
响应示例：
{
"total": 2,
"subtotal": 2,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results":
output truncatedAPI 的响应表示总计有两个结果，这是结果的第一个页面，每个页面的最大结果设置为 20。如需更多信息，请参阅 第 3.2 节 “JSON 响应格式”。
3.1.2. 使用 POST HTTP 方法
使用 POST HTTP 动词将数据提交到 API，以创建条目或资源。您必须使用 JSON 格式提交数据。如需更多信息，请参阅 第 5.1.1 节 “将 JSON 数据传递给 API 请求”。
创建激活码的示例
创建包含以下内容的测试文件，如
activation-key.json：{"organization_id":1, "name":"TestKey", "description":"Just for testing"}通过在
activation-key.json文件中应用数据来创建激活码：请求示例：
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request POST \ --user My_User_Name:My_Password \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys \ | python3 -m json.tool
响应示例：
{ "id": 2, "name": "TestKey", "description": "Just for testing", "unlimited_hosts": true, "auto_attach": true, "content_view_id": null, "environment_id": null, "usage_count": 0, "user_id": 3, "max_hosts": null, "release_version": null, "service_level": null, "content_overrides": [ ], "organization": { "name": "Default Organization", "label": "Default_Organization", "id": 1 }, "created_at": "2017-02-16 12:37:47 UTC", "updated_at": "2017-02-16 12:37:48 UTC", "content_view": null, "environment": null, "products": null, "host_collections": [ ], "permissions": { "view_activation_keys": true, "edit_activation_keys": true, "destroy_activation_keys": true } }- 验证新激活密钥是否存在。在 Satellite Web UI 中，进入到 Content > Lifecycle > Activation Keys 来查看您的激活码。
3.1.3. 使用 PUT HTTP 方法
使用 PUT HTTP 方法更改现有值或附加到现有资源。您必须使用 JSON 格式提交数据。更多信息请参阅 第 5.1.1 节 “将 JSON 数据传递给 API 请求”。
示例
本例更新在上例中创建的 TestKey 激活码。
编辑之前创建的
activation-key.json文件，如下所示：{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }在 JSON 文件中应用更改：
请求示例：
$ curl --request PUT \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --user My_User_Name:My_Password \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -m json.tool
响应示例：
{ "id": 2, "name": "TestKey", "description": "Just for testing", "unlimited_hosts": false, "auto_attach": true, "content_view_id": null, "environment_id": null, "usage_count": 0, "user_id": 3, "max_hosts": 10, "release_version": null, "service_level": null, "content_overrides": [ ], "organization": { "name": "Default Organization", "label": "Default_Organization", "id": 1 }, "created_at": "2017-02-16 12:37:47 UTC", "updated_at": "2017-02-16 12:46:17 UTC", "content_view": null, "environment": null, "products": null, "host_collections": [ ], "permissions": { "view_activation_keys": true, "edit_activation_keys": true, "destroy_activation_keys": true } }- 在 Satellite Web UI 中，导航到 Content > Lifecycle > Activation Keys 来验证更改。
3.1.4. 使用 DELETE HTTP 方法
要删除资源，请使用 DELETE 方法以及包含您要删除的资源 ID 的 API 路由。
Example
这个示例删除 ID 为 2 的 TestKey 激活码：
请求示例：
$ curl \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --request DELETE \ --user My_User_Name:My_Password \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -m json.tool
响应示例：
output omitted "started_at": "2017-02-16 12:58:17 UTC", "ended_at": "2017-02-16 12:58:18 UTC", "state": "stopped", "result": "success", "progress": 1.0, "input": { "activation_key": { "id": 2, "name": "TestKey" output truncated
