第 2 章 API 参考
您的 Satellite 服务器上位于 https://satellite.example.com/apidoc/v2.html 的完整 API 引用。请注意，虽然 Satellite 6 API 版本 1 和 2 可用，但红帽只支持版本 2。
2.1. 了解 API 语法
以下示例请求使用 python3 来格式化 Satellite 服务器中的 respone。在 RHEL 7 和一些较旧的系统中，您必须使用 python 而不是 python3。
内置的 API 引用显示 API 路由或路径，前面带有 HTTP 动词：
HTTP_VERB API_ROUTE
要使用 API，请使用 curl 命令语法和参考文档中的 API 路由来构建命令：
$ curl --request HTTP_VERB \ 1 --insecure \ 2 --user sat_username:sat_password \ 3 --data @file.json \ 4 --header "Accept:application/json" \ 5 --header "Content-Type:application/json" \ 6 --output file 7 API_ROUTE \ 8 | python3 -m json.tool 9
- 1
- 要将
curl用于 API 调用，请使用--request选项指定 HTTP 动词。例如，--request POST。 - 2
- 添加
--insecure选项以跳过 SSL peer 证书验证检查。 - 3
- 使用
--user选项为用户提供凭据。 - 4
- 5 6
- 7
- 从 Satellite 服务器下载内容时，请使用
--output选项指定输出文件。 - 8
- 使用以下格式的 API 路由：
https://satellite.example.com/katello/api/activation_keys。在 Satellite 6 中，API 的版本 2 是默认的。因此，不需要在 URL 中使用v2进行 API 调用。 - 9
- 将输出重定向到 Python
json.tool模块，以便更轻松地读取输出。
2.1.1. 使用 GET HTTP 动词
使用 GET HTTP 动词从 API 获取有关现有条目或资源的数据。
示例
本例请求 Satellite 主机数量：
请求示例：
$ curl --request GET --insecure --user sat_username:sat_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。更多信息请参阅 第 2.2 节 “了解 JSON 响应格式”。
2.1.2. 使用 POST HTTP 动词
使用 POST HTTP 动词将数据提交到 API，以创建条目或资源。您必须使用 JSON 格式提交数据。更多信息请参阅 第 4.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 sat_username:sat_password --insecure \ --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 > Activation keys 以查看您的激活码。
2.1.3. 使用 PUT HTTP 动词
使用 PUT HTTP 动词更改现有值或附加到现有资源。您必须使用 JSON 格式提交数据。更多信息请参阅 第 4.1.1 节 “将 JSON 数据传递给 API 请求”。
示例
本例更新上例中创建的 TestKey 激活码。
编辑之前创建的
activation-key.json文件，如下所示：{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }应用 JSON 文件中的更改：
请求示例：
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request PUT \ --user sat_username:sat_password --insecure \ --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 > Activation keys 来验证更改。
2.1.4. 使用 DELETE HTTP 动词
要删除资源，请使用 DELETE 动词以及包含您要删除的资源 ID 的 API 路由。
示例
这个示例删除 ID 为 2 的 TestKey 激活码：
请求示例：
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request DELETE \ --user sat_username:sat_password --insecure \ 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
2.1.5. 将 API 错误消息与 API 引用相关联
API 使用 RAILs 格式来指示错误：
Nested_Resource.Attribute_Name
这会转换为 API 引用中使用的以下格式：
Resource[Nested_Resource_attributes][Attribute_Name_id]
