API
如何使用 API
API 有自己的用户界面,你可以从 Web 浏览器访问它。这是查看资源、执行操作以及查看等效 cURL 或 HTTP 请求和响应的一种简单的方法。要访问它:
- Rancher v2.6.4+
- Rancher 版本低于 v2.6.4
- 单击右上角的用户头像。
- 单击账号 & API 密钥。
- 在 API 密钥下,找到 API 端点字段并单击链接。该链接类似于
https://<RANCHER_FQDN>/v3
,其中<RANCHER_FQDN>
是 Rancher deployment 的完全限定域名。
转到位于 https://<RANCHER_FQDN>/v3
的 URL 端点,其中 <RANCHER_FQDN>
是你的 Rancher deployment 的完全限定域名。
认证
API 请求必须包含认证信息。认证是通过 API 密钥使用 HTTP 基本认证完成的。API 密钥可以创建新集群并通过 /v3/clusters/
访问多个集群。集群和项目角色会应用于这些键,并限制账号可以查看的集群和项目以及可以执行的操作。
默认情况下,某些集群级别的 API 令牌是使用无限期 TTL(ttl=0
)生成的。换言之,除非你让令牌失效,否则 ttl=0
的 API 令牌永远不会过期。有关如何使 API 令牌失效的详细信息,请参阅 API 令牌。
发出请求
该 API 通常是 RESTful 的,但是还具有多种功能。这些功能可以使客户端发现所有内容,因此可以编写通用客户端,而不必为每种资源编写特定代码。有关通用 API 规范的详细信息,请参阅此处。
- 每种类型都有一个 Schema,这个 Schema 描述了以下内容:
- 用于获取此类资源集合的 URL
- 资源可以具有的每个字段及其类型、基本验证规则、是必填还是可选字段等
- 在此类资源上可以执行的每个操作,以及它们的输入和输出(也作为 schema)
- 允许过滤的每个字段
- 集合本身或集合中的单个资源可以使用的 HTTP 操作方法
因此,你可以只加载 schema 列表并了解 API 的所有信息。实际上,这是 API 的 UI 工作方式,它不包含特定于 Rancher 本身的代码。每个 HTTP 响应中的
X-Api-Schemas
标头都会发送获取 Schemas 的 URL。你可以按照每个 schema 上的collection
链接了解要在哪里列出资源,并在返回资源中的其他links
中获取其他信息。在实践中,你可能只想构造 URL 字符串。我们强烈建议将此限制为在顶层列出的集合 (
/v3/<type>
),或获取特定资源 (/v3/<type>/<id>
)。除此之外的任何内容都可能在将来的版本中发生更改。资源之间相互之间有联系,称为链接(links)。每个资源都包含一个
links
映射,其中包含链接名称和用于检索该信息的 URL。同样,你应该GET
资源并遵循links
映射中的 URL,而不是自己构造这些字符串。大多数资源都有操作(action),表示可以执行某个操作或改变资源的状态。要使用操作,请将 HTTP
POST
请求发送到actions
映射中你想要的操作的 URL。某些操作需要输入或生成输出,请参阅每种类型的独立文档或 schema 以获取具体信息。要编辑资源,请将 HTTP
PUT
请求发送到资源上的links.update
链接,其中包含要更改的字段。如果链接丢失,则你无权更新资源。未知字段和不可编辑的字段将被忽略。要删除资源,请将 HTTP
DELETE
请求发送到资源上的links.remove
链接。如果链接丢失,则你无权更新资源。要创建新资源,HTTP
POST
到 schema(即/v3/<type>
)中的集合 URL。
过滤
你可以使用 HTTP 查询参数的公共字段在服务器端过滤大多数集合。filters
映射显示了可以过滤的字段,以及过滤后的值在你发起的请求中是什么。API UI 具有设置过滤和显示适当请求的控件。对于简单的 "equals" 匹配,它只是 field=value
。你可以将修饰符添加到字段名称,例如 field_gt=42
表示“字段大于 42”。详情请参阅 API 规范。
排序
你可以使用 HTTP 查询参数的公共字段在服务器端排序大多数集合。sortLinks
映射显示了可用的排序,以及用于获取遵循该排序的集合的 URL。它还包括当前响排序依据的信息(如果指定)。
分页
默认情况下,API 响应以每页 100 个资源的限制进行分页。你可以通过 limit
查询参数进行更改,最大为 1000,例如 /v3/pods?limit=1000
。集合响应中的 pagination
映射能让你知道你是否拥有完整的结果集,如果没有,则会指向下一页的链接。
捕获 Rancher API 调用
你可以使用浏览器开发人员工具来捕获 Rancher API 的调用方式。例如,你可以按照以下步骤使用 Chrome 开发人员工具来获取用于配置 RKE 集群的 API 调用:
- 在 Rancher UI 中,转到集群管理并单击创建。
- 单击某个集群类型。此示例使用 Digital Ocean。
- 使用集群名称和节点模板填写表单,但不要单击创建。
- 在创建集群之前,你需要打开开发人员工具才能看到正在记录的 API 调用。要打开工具,右键单击 Rancher UI,然后单击检查。
- 在开发者工具中,单击 Network 选项卡。
- 在 Network 选项卡上,确保选择了 Fetch/XHR。
- 在 Rancher UI 中,单击创建。在开发者工具中,你应该会看到一个名为
cluster?_replace=true
的新网络请求。 - 右键单击
cluster?_replace=true
并单击复制 > 复制为 cURL。 - 将结果粘贴到文本编辑器中。你将能够看到 POST 请求,包括被发送到的 URL、所有标头以及请求的完整正文。此命令可用于从命令行创建集群。请注意,请求包含凭证,因此请将请求存储在安全的地方。
启用在 API 中查看
你还可以查看针对各自集群和资源捕获的 Rancher API 调用。 默认情况下不启用此功能。 要启用它:
- 单击 UI 右上角的 用户图标,然后从下拉菜单中选择 偏好设置
- 在高级功能部分下,单击启用"在 API 中查看"
选中后,在 API 中查看链接现在将显示在 UI 资源页面上的 ⋮ 子菜单下。