如何使用 API

API 具有独立的用户界面，您可从 Web 浏览器访问它。这是查看资源、执行操作以及查看等效 cURL 或 HTTP 请求和响应的最简便方法。要访问它，请单击右上角用户头像，在 API & Keys 下，您可以找到 API 访问地址，并且可以创建API KEY。

认证

API 请求必须包含身份验证信息。身份验证是通过使用带有API KEY的 HTTP 的基本验证（Basic Auth）完成的。API KEY 可以创建新的集群，并可以通过/v3/clusters/访问多个集群。可以将集群和项目角色绑定到这些 KEY 上，从而限制用户可以看到哪些集群和项目，以及它们可以执行哪些操作。

默认情况下，一些集群级别的 API KEY 是永不过期的，因为他们使用ttl=0生成。如不再需要这些 API KEY，可以删除这些 KEY 使其失效，有关操作说明请阅读API Token 页面。

发送请求

该 API 通常是 RESTful 的，但是还具有多种功能。这些功能可以使客户端能够发现所有内容，因此可以编写通用客户端，而不必为每种类型的资源编写特定的代码。有关通用 API 规范的详细信息，请参见API 规范。

• 每种类型都有一个 Schema，这个 Schema 描述了以下内容：

  • 用于获取此类资源集合的 URL。
  • 资源可以具有的每个字段及其类型，基本验证规则（例如，是必填字段还是可选字段）。
  • 对这种类型的资源可能进行的所有操作，包括其输入和输出（也作为 Schema。）
  • 允许过滤的每个字段。
  • 哪些 HTTP 方法可用于集合本身或集合中的单个资源。

• 因此，理论上讲，您可以仅加载 Schema 列表并了解有关 API 的所有信息。实际上，这就是 API UI 的工作方式，它不包含特定于 Rancher 本身的代码。获取 Schema 的 URL 将在每个 HTTP 响应中的X-Api-Schemas头里。从那里，您可以按照每个 Schema 上的collection链接来了解在何处列出资源，以及返回资源中的其他links以获取任何其他信息。

• 实际上，您可能只想构造 URL 字符串。我们强烈建议将其限制在顶层列出的集合（/v3/<type>）或获取特定资源（/v3/<type>/<id>）。除此之外的任何内容都可能在将来的版本中发生更改。

• 资源之间相互之间有联系，称为链接。每个资源都包含一个links映射，其中包含链接名称和用于检索该信息的 URL。同样，您应该 GET 资源，然后使用links映射中的 URL，而不是自己构造这些字符串。

• 大多数资源都有操作，这些操作可以执行某些操作或更改资源的状态。要使用这些功能，请将 HTTP POST 请求发送到您想要的操作的actions映射中的 URL。有些操作需要输入或会产生输出，有关每种信息，请参阅每种类型的单独文档或 Schema。

• 要编辑资源，请将 HTTP PUT 请求发送到资源上的links.update链接，在请求中中包含您要更改的字段。如果缺少链接，则您无权更新资源。未知字段和不可编辑的字段将被忽略。

• 要删除资源，请将 HTTP DELETE 请求发送到资源上的links.remove链接。如果缺少链接，则您无权删除资源。

• 要创建新资源，请在 Schema 中的集合 URL（为/v3/<type>）上发送 HTTP POST请求。

过滤

可以使用 HTTP 查询参数，在服务器端过滤大多数集合。过滤器映射向您显示可以过滤哪些字段，以及相应的过滤值。API 用户界面具有用于设置过滤条件并向您显示适当请求的控件。对于简单的“等于”匹配，它只是field = value。您也可以将修饰符添加到字段名称中，例如 field_gt = 42 表示“field 大于 42”。有关完整详细信息，请参见API 规范。

排序

大多数集合可以使用 HTTP 查询参数，在服务器端根据某些参数进行排序。sortLinks映射显示了可用的排序种类以及 URL，可以根据这些 URL 对集合进行排序。它还包括有关当前响应排序的信息（如果已指定）。

分页

默认情况下，API 响应的页面分页限制为每页 100 个资源。可以通过limit查询参数进行更改，最多可以设置为1000，例如：/v3/pods?limit=1000。集合响应中的分页映射告诉您是否拥有完整的查询结果，如果没有完整结果，则提供下一页的链接。