Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 2 章 API 参考

Satellite 服务器上提供了完整的 API 参考 https://satellite6.example.com/apidoc/v2.html （将 satellite6.example.com 替换为 Satellite 服务器的主机名）。请注意，即使 Satellite 6 API 版本 1 和 2 可用，但红帽只支持版本 2。

2.1. 了解 API 语法
复制链接

内置 API 引用显示 API 路由或路径，前面带有 HTTP 动词：
HTTP_VERB API_ROUTE
Copy to Clipboard Toggle word wrap
API 使用的 HTTP 动词为 GET、POST、PUT 和 DELETE。有关一些示例，请参见位于 http://satellite6.example.com/apidoc/v2/hosts.html 的 API 参考文档的 HOSTS 部分。如果您已熟悉 API 语法，并且 curl 命令您可以跳过本节。
要使用 API，请使用参考文档中的 API 路由和命令语法中的 API 路由构建命令。例如： curl 手册页显示以下基本语法： 
curl [options] [URL...]
Copy to Clipboard Toggle word wrap
本指南中使用的选项包括：-- X、--request 命令，其中 command 是 HTTP 动词。

使用 GET HTTP Verb

GET HTTP 动词用于从 API 获取现有条目或资源的数据。
将 API HOSTS 部分中的示例（如 GET /api/hosts 和 curl 语法）相结合： 
curl -X GET https://satellite6.example.com/api/hosts
Copy to Clipboard Toggle word wrap
Satellite 只支持连接到 API 的 HTTPS，并且需要某种形式的身份验证。
对于可用的示例，我们必须至少添加带有 the -u 选项的用户名，并使用 -k 选项跳过 SSL 对等证书验证检查： 
$ curl -X GET -k -u sat_username https://satellite6.example.com/api/hosts
Enter host password for user 'sat_username':
{
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
	output truncated
Copy to Clipboard Toggle word wrap
上述 API 响应表明总计有两个结果，在下面返回两个结果，这是结果的第一个页面，每个页面的最大结果设置为 20。这在 第 2.2 节 “了解 JSON 响应格式” 中更为详细地解释。
API 引用中的一些示例包括以 :参数 形式前面以冒号开头的术语。例如： 
GET /api/hosts/:id
Copy to Clipboard Toggle word wrap
这些是 API 路由参数，且必须替换为适当的值。路由参数以冒号开头，并以 id 结尾。
注意
在 Satellite 6 中，API 的版本 2 是默认值。因此，在 API 调用的 URL 中不需要使用 v2。

使用 POST HTTP Verb

POST HTTP 动词用于将数据提交到 API，以创建新条目或资源。数据必须采用 JSON 格式，并可使用 -d, --data 选项包含内联，后跟带引号的 JSON 格式的数据（用大括号 {} 括起）。或者，未加引号的 JSON 格式的数据可以包含在文件中，并使用 curl 命令的 @ 选项指定。例如，-d @file.json。
将外部文件用于 JSON 格式的数据的优点包括较少的问题：引用和转义，可以使用您喜欢的编辑器，以帮助查找和避免错误，以及外部工具检查 JSON 数据的有效性或重新格式化它。例如，ya jl 软件包包含 json_verify 工具和 json_reformat 工具。
使用 json_verify 工具，您可以检查 JSON 文件的有效性，如下所示： 
$ json_verify < test_file.json
Copy to Clipboard Toggle word wrap
API 调用返回的无结构 JSON 数据可以通过 python 模块 json.tool 传送：
curl API_call | python -m json.tool
Copy to Clipboard Toggle word wrap
Alternately，使用 json_reformat 工具： 
curl API_call | json_reformat
Copy to Clipboard Toggle word wrap
输出格式在 第 2.2 节 “了解 JSON 响应格式” 中解释。
API 参考在 Activation keys 部分中包括以下内容： 
POST /katello/api/activation_keys
Copy to Clipboard Toggle word wrap
这是 POST /katello/api/activation_keys 命令的可能格式： 
curl -X POST -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys
Copy to Clipboard Toggle word wrap
要查看 POST HTTP 动词如何工作，请创建一个测试文件，如 activation-key.json，其内容如下： 
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
Copy to Clipboard Toggle word wrap
以下示例将通过应用刚才创建的文件中的数据来创建新的激活码： 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X POST \
-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys | json_reformat
{
    "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
    }
}
Copy to Clipboard Toggle word wrap
要在 Web UI 中查看此条目，请导航到 Content Activation keys。记住在任何更改后重新加载页面。

使用 PUT HTTP Verb

PUT HTTP 动词用于将数据提交到 API，以更新现有条目或资源。与 POST API 调用类似，数据必须采用 JSON 格式，并可使用 -d, --data 选项加上带引号的 JSON 格式的数据（用大括号 {} 括起）。或者，未加引号的 JSON 格式的数据可以包含在文件中，并使用 curl 命令的 @ 选项指定。例如，-d @file.json。
若要更改现有值或附加到现有资源，可使用 PUT HTTP 动词。API 引用有以下条目可用于更新激活码： 
PUT /katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
要更新现有的激活码，请使用以下格式的命令： 
curl -X PUT -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
使用要更新的激活码的 ID 替换 :id。将 PUT 命令与相同值一起使用多次 不会创建 多个条目。
例如，可以通过编辑之前创建的文件来更新上例中创建的 test Activation 密钥，如下所示： 
{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
Copy to Clipboard Toggle word wrap
按如下所示使用命令在 JSON 文件中应用更改： 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X PUT \
-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys/2
{
    "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
    }
}
Copy to Clipboard Toggle word wrap

使用 DELETE HTTP Verb

要删除资源，请将 DELETE 动词与包含要删除的资源的 ID 的 API 路由一起使用。
要删除现有的激活码，请使用以下格式的命令： 
curl -X DELETE -k -u sat_username:sat_password \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
使用要删除的激活码的 ID 替换 :id。例如： 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X DELETE \
-u admin:RedHat1! -k \
https://satellite6.example.com/katello/api/activation_keys/2 | json_reformat
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
Copy to Clipboard Toggle word wrap

与 API 参考相关的 API 错误消息

API 使用 RAILs 格式来指示错误： 
Nested_Resource.Attribute_Name
Copy to Clipboard Toggle word wrap
这会转换为 API 引用中使用的以下格式： 
Resource[Nested_Resource_attributes][Attribute_Name_id]
Copy to Clipboard Toggle word wrap

2.2. 了解 JSON 响应格式
复制链接

使用 GET 调用 API 将以 JSON 格式返回结果。通过 Python json.tool 模块传递输出会带来更人类可读的格式。

Collections 的 JSON 响应格式

集合是对象列表，如主机和域。集合 JSON 响应的格式由 metadata 字段部分组成，后跟 results 部分。以下是使用 API 路由 GET /api/domains 时用于域列表的集合 JSON 响应的格式示例。输出通过 json.tool 传送，以便更轻松地阅读结果部分。 
$ curl -X GET -k -u admin:password https://satellite6.example.com/api/domains | python -m json.tool
{
    "total": 3,
    "subtotal": 3,
    "page": 1,
    "per_page": 20,
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "results": [
        {
            "id": 23,
            "name": "qa.lab.example.com",
            "fullname": "QA",
            "dns_id": 10,
            "created_at": "2013-08-13T09:02:31Z",
            "updated_at": "2013-08-13T09:02:31Z"
        },
        {
            "id": 25,
            "name": "sat.lab.example.com",
            "fullname": "SATLAB",
            "dns_id": 8,
            "created_at": "2013-08-13T08:32:48Z",
            "updated_at": "2013-08-14T07:04:03Z"
        },
        {
            "id": 32,
            "name": "hr.lab.example.com",
            "fullname": "HR",
            "dns_id": 8,
            "created_at": "2013-08-16T08:32:48Z",
            "updated_at": "2013-08-16T07:04:03Z"
        }
    ]
}
Copy to Clipboard Toggle word wrap
响应元数据字段如下所述：
  • total - 没有搜索参数的对象总数。
  • Subtotal- 使用给定搜索参数返回的对象数量（如果没有搜索，则 subtotal 等于 total）。
  • page - 页面号。
  • per_page - 每个页面返回的最大对象数。
  • Limit - 在集合响应中返回指定数量的对象。
  • offset - 返回集合前跳过的对象数量。
  • search - 基于 scoped_scoped 语法的搜索字符串。
  • 排序
    • 按 - 集合排序的字段。
    • 顺序 -排序顺序，可以是升序的 ASC 或 DESC （降序）。
  • results - 对象集合。

单个对象的 JSON 响应格式

单对象 JSON 响应用于显示单个对象。GET 请求需要对象的唯一标识符 :id 或 :name。请注意，:name 不能始终用作唯一标识符，但 :id 始终可以被使用。单对象 JSON 响应的格式仅由对象的属性组成。
以下是使用 API 路由 GET /api/domains/23 或 GET /api/domains/qa.lab.example.com 时，单对象 JSON 响应的格式示例。 
$ curl -X GET -k -u admin:password https://satellite6.example.com/api/domains/23 | python -m json.tool
{
    "id": 23,
    "name": "qa.lab.example.com",
    "fullname": "QA",
    "dns_id": 10,
    "created_at": "2013-08-13T09:02:31Z",
    "updated_at": "2013-08-13T09:02:31Z"
}
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat