第 2 章 API 参考
完整的 API 引用位于 https://satellite.example.com/apidoc/v2.html 的卫星服务器上。请注意，即使有 Satellite 6 API 的版本 1 和 2，红帽仅支持版本 2。
2.1. 了解 API 语法
内置 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 | python -m json.tool 9
- 1
- 要将
curl用于 API 调用，请使用--request选项指定 HTTP 动词。例如：--request POST。 - 2
- 添加
--insecure选项以跳过 SSL peer 证书验证检查。 - 3
- 使用
--user选项提供用户凭据。 - 4
- 5 6
- 7
- 从卫星服务器下载内容时，请使用
--output选项指定输出文件。 - 8
- 使用以下格式的 API 路由：
https://satellite.example.com/katello/api/activation_keys。在 Satellite 6 中，API 的版本 2 是默认值。因此，不需要在 API 调用的 URL 中使用v2。 - 9
- 将输出重定向到 Python
json.tool模块，以便更轻松地读取输出。
2.1.1. 使用 GET HTTP Verb
使用 GET HTTP 动词从 API 中获取现有条目或资源的数据。
示例
这个示例请求 Satellite 主机的数量：
请求示例：
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/hosts | python -m json.tool
响应示例：
{
"total": 2,
"subtotal": 2,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results":
output truncated来自 API 的响应表示总共有两个结果，这是结果的第一个页面，每个页面最大结果设置为 20。更多信息请参阅 第 2.2 节 “了解 JSON 响应格式”。
2.1.2. 使用 POST HTTP Verb
使用 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 \ | python -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 Verb
使用 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 \ | python -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 Verb
要删除资源，可将 DELETE 动词与 API 路由一起使用，该路由中包含您要删除的资源 ID。
示例
这个示例删除 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 \ | python -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]
