HTTP 详细信息
建议更改
PDF
Astra Control REST API 使用 HTTP 以及相关参数对资源和集合执行操作。下面提供了 HTTP 实施的详细信息。
API 事务和 CRUD 模型
Astra Control REST API 可实施一个事务模式，其中包含定义明确的操作和状态过渡。
每次 REST API 调用都是作为对 Astra 服务的 HTTP 请求执行的。每个请求都会向客户端生成关联的响应。此请求响应对可视为 API 事务。
通过 Astra Control REST API 提供的每个资源实例和集合均可根据 * CRU* 模型进行访问。有四个操作，每个操作都映射到一个 HTTP 方法。这些操作包括：
-
创建
-
读取
-
更新
-
删除
对于某些 Astra 资源，仅支持其中一部分操作。您应查看 "API 参考" 有关特定 API 调用的详细信息。
HTTP 方法
下表显示了 API 支持的 HTTP 方法或动词。
| 方法 | CRUD | Description |
|---|---|---|
获取 |
读取 |
检索资源实例或集合的对象属性。在与集合结合使用时，此操作被视为 * 列表 * 操作。 |
发布 |
创建 |
根据输入参数创建新的资源实例。长期 URL 会在 |
PUT |
更新 |
使用提供的 JSON 请求正文更新整个资源实例。系统会保留用户不可修改的密钥值。 |
删除 |
删除 |
删除现有资源实例。 |
请求和响应标头
下表汇总了与 Astra Control REST API 一起使用的 HTTP 标头。
|
请参见 "RFC 7232" 和 "RFC 7233" 有关详细信息 … |
| 标题 | Type | 使用说明 |
|---|---|---|
接受 |
请求 |
如果值为 "/" 或未提供，则在内容类型响应标题中返回 |
Authorization |
请求 |
包含用户 API 密钥的承载令牌。 |
内容类型 |
响应 |
根据 |
ETAG |
响应 |
随 RFC 7232 中定义的成功附带。该值是整个 JSON 资源的 MD5 值的十六进制表示形式。 |
如果匹配 |
请求 |
一个前提条件请求标头，如第 3.1 节 RFC 7232 中所述实施，并支持 * PUT * 请求。 |
if-Modified-since |
请求 |
一个前提条件请求标头，如第 3.4 节 RFC 7232 中所述实施，并支持 * PUT * 请求。 |
如果未修改，则从 |
请求 |
一个前提条件请求标头，如第 3.4 节 RFC 7232 中所述实施，并支持 * PUT * 请求。 |
位置 |
响应 |
包含新创建资源的完整 URL 。 |
查询参数
以下查询参数可用于资源收集。请参见 "使用收集" 有关详细信息 …
| 查询参数 | Description |
|---|---|
包括 |
包含读取收集时应返回的字段。 |
筛选器 |
指示读取收集时要返回的资源必须匹配的字段。 |
订单 |
确定读取收集时返回的资源的排序顺序。 |
limit |
限制读取集合时返回的最大资源数。 |
跳过 |
设置读取集合时要传递和跳过的资源数量。 |
count |
指示是否应在元数据对象中返回资源总数。 |
HTTP status codes
下面介绍了 Astra Control REST API 使用的 HTTP 状态代码。
|
|
Astra Control REST API 还使用 * HTTP APIs* 标准的问题详细信息。请参见 "诊断和支持" 有关详细信息 … |
| 代码 | 含义 | Description |
|---|---|---|
200 |
确定 |
表示未创建新资源实例的调用成功。 |
201 |
已创建 |
已成功创建对象，并且位置响应标头包含该对象的唯一标识符。 |
204 |
No Content |
尽管未返回任何内容，但请求成功。 |
400 |
请求错误 |
此请求输入无法识别或不适当。 |
401 |
未授权 |
用户未获得授权，必须进行身份验证。 |
403 |
已禁止 |
由于授权错误，访问被拒绝。 |
404 |
未找到 |
请求中引用的资源不存在。 |
409 |
冲突 |
尝试创建对象失败，因为此对象已存在。 |
500 |
内部错误 |
服务器发生一般内部错误。 |
503 |
服务不可用 |
由于某种原因，此服务尚未准备好处理此请求。 |