技术文档
OIS

# 规范细节

Table of Contents

预言机集成规范 (OIS) 基于 Open API 规范（OAS） (opens new window)，但存在一些不同，在作用于 OIS 文件时肯定会侧重于以下文档所提的内容。

OAS

我们不建议在创建OIS对象时参考OAS的帮助。 OIS只是借用了OAS的格式实践。 创建OIS对象所需的一切都在这些文档中。

看这篇文章，设置预言机集成标准 (opens new window)以了解OIS的概况。

  • 由 (*) 表示的字段用于文档目的，不被Airnode使用。
  • OIS字段应该由集成方审核和定制。
  • 所有的URLs都是绝对路径（就是说相对路径 (opens new window)是不支持的）。

# OIS 对象摘要

OIS有五个根域(key)。

  1. oisFormat
  2. title
  3. version
  4. apiSpecifications
  5. endpoints

apiSpecifications描述了API的操作，它被映射到 endpoints，Airnode在链上公开了这些节点。

{
  "oisFormat": "1.0.0",
  "title": "myOisTitle",
  "version": "1.2.3",
  "apiSpecifications": {
    ...
  },
  "endpoints": [
    ...
  ]
}
  },
  "endpoints": [
    ...
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 1. 1. oisFormat

(必填) 在生成规范时遵循的 OIS 格式版本。

# 2. 2. title

(必填) OIS标题。 标题字段最多为64个字符，只能包含字母数字字符、连字符、下划线和空格。

# 3. 3. version

(必填) 用户定义的 OIS 对象。 不要与 oisForm 版本混淆，oisForm定义的是 OIS 格式。

# 4. 4. apiSpecifications

(必填) 指定的API对象，有以下根级字段：

// apiSpecifications
{
  "servers": [
    {
      "url": "https://myapi.com/api/v1"
    }
  ],
  "paths": {
    "/myPath": {
      "get": {
        "parameters": [
          {
            "name": "myParameter",
            "in": "query"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "mySecurityScheme1": {
        "type": "apiKey",
        "name": "X-MY-API-KEY",
        "in": "query"
      }
    }
  },
  "security": {
    "mySecurityScheme1": []
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 4.1. 4.1. servers

(必填) 一个包含API的基本URL的对象数组。 数组中只允许一个对象 (即基础URL)。 适用于所有 API 操作。

# 4.2. 4.2. paths

(必填) 指的是一个API操作的参数的对象，有以下元素：

# 4.2.1. parameters

(必填) API操作参数的列表，每个参数都有以下字段：

  • name
  • in
# 4.2.1.1. name

(必填) 参数名称。

# 4.2.1.2. in in

(必填) 参数的位置。 当集成的是 POST 方法时，用in: query定义body参数。 Airnode 会将所有 query 类型转换为 requestBody. 请注意，只支持非嵌套的 application/json 内容类型。 Note that only the non-nested application/json content-type is supported.

允许的值： query, header, path, cookie。

# 4.3. 4.3. components

info (必填) 一个对象，在 securitySchemes.{securitySchemeName} 下可以找到安全方案，有以下元素：

  • type
  • name
  • in
  • scheme

# 4.3.1. type type

(必填) 安全方案的类型。

允许的值：

  • 用于 API 操作来验证Airnode。
    • apiKey
    • http
  • 允许API操作获取请求者和（/或）链的信息。
    • relayRequesterAddress
    • relaySponsorAddress
    • relaySponsorWalletAddress
    • relayChainId
    • relayChainType

# 4.3.2. name

(只有 类型 是 apiKey 时) 安全方案变量的名称。

# 4.3.3. in in

(仅当类型是 apiKey时) 安全类型变量的位置。

允许的值： query, header, cookie

# 4.3.4. scheme scheme

(仅当 type 是 http时) HTTP 授权方案名称，被用于授权header，其定义在[RFC7235 ](https://tools. ietf.org/html/rfc7235#section-5.1) 中。

允许的值：(basic 和 bearer)。

"mySecurityScheme2": {
  "type": "http",
  "scheme": "bearer"
}
```<!--The values used SHOULD be registered in the \[IANA Authentication Scheme registry\](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The OIS object supports--><!--OAS equivalent: `components.securitySchemes.{securitySchemeName}.scheme`.-->

### 4.4. `security`

(Required) An object containing all security schemes required by an API call. 适用于所有操作。 安全方案可以包含API要求的信息，以验证Airnode，以及API可能需要的请求者的信息（中继信息）。 关于更多安全方案，在 _构建一个 Airnode_ 指南的\[API 安全\](../../airnode/v0.5/grp-providers/guides/build-an-airnode/api-security.md)部分和_概念和定义_ 中的\[Airnode 身份验证\](../../airnode/v0.5/concepts/airnode-auth.md) 部分。

`security` 对象保留了所有使用过的安全方案的名称。 在 `security` 中的每一个安全方案都映射到空列表。 空列表会被用于Airnode未来提供给个人节点认证的版本。 `components.securitySchemes。 {name}` 对象定义了安全方案。 不像OAS，`security` 是一个对象，不是一个数组。

```json
```json
// OIS object
"components": {
  "securitySchemes": {
    "my-api-key-scheme": {
      "in": "query",
      "type": "apiKey",
      "name": "access_key"
      "scheme": "<FILL_*>" // Used when type="http".
    }
  }
},
"security": {
  "my-api-key-scheme": []
}
    }
  }
},
"security": {
  "my-api-key-scheme": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

apiCredential 对象 (不属于OIS 对象的一部分) 持有任何安全方案所需的凭据。

// config.json root object.
// Not part of the OIS object.
"apiCredentials": [
    {
      "oisTitle": "my-ois-title", // Must match the ois.title field the security scheme is in.
      "securitySchemeName": "my-api-key-scheme",
      "securitySchemeValue": "${API_KEY}" // In secrets.env
    }
  ]
1
2
3
4
5
6
7
8
9

请注意:

目前Airnode 从 component.securitySchemes 读取安全方案，而不是 security。 现在使用 security 字段（与 component.securitySchemes）提供了一个平稳过渡到未来的Airnode版本的安全方案实现。 这将允许将安全方案分配给单个API操作。 目前安全方案是分配给整个API。

# 5. 5. endpoints

(必填) 对象的列表，每个对象指定一个带有以下字段的 Airnode终端节点：

// endpoints
[
  {
    "name": "convertToUsd",
    "operation": {
      "path": "/myPath",
      "method": "get"
    },
    "fixedOperationParameters": [
      {
        "operationParameter": {
          "name": "to",
          "in": "query"
        },
        "value": "USD"
      }
    ],
    "reservedParameters": [
      {
        "name": "_type",
        "fixed": "int256"
      },
      {
        "name": "_path",
        "default": "data.0.price"
      },
      {
        "name": "_times"
      }
    ],
    "parameters": [
      {
        "name": "from",
        "default": "EUR",
        "operationParameter": {
          "name": "from",
          "in": "query"
        }
      }
    ]
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 5.1. name

(必填) 在apiSpecifications.path中定义的 API 操作的对象具有以下元素：

# 5.2. 5.2. operation

(必填) 一个具有以下元素的 API 操作参数的对象：

  • path
  • method

# 5.2.1. path path

(必填) API 操作的方法。

# 5.2.2. 5.2.2. method

(必填) API 操作的路径。

允许的值： get, post

# 5.3. 5.3. fixedOperationParameters

info (必填) 对应 API 操作的固定参数的对象列表。 当需要时，fixedOperationParameters 数组可以留空。 每个对象有以下要素：

  • operationParameter
  • value

# 5.3.1. operationParameter

必须是三个可能的值之一（query, header, path, cookie）。

  • name
  • in
# 5.3.1.2. in name

(必填) 不能被请求者覆盖的 API 操作的参数的值。

# 5.3.1.2. in

Must be one of three possible values (query, header, path, cookie).

# 5.3.2. 5.3.2. value

API操作参数的名称，该参数将具有固定值。

# 5.4. 5.4. reservedParameters

info (可选) 指定保留的Airnode节点参数的对象列表，这些参数没有映射到任何API操作参数，但被Airnode用于特殊目的。 请参阅 保留参数文档以获得深入解释。 每个对象都有以下元素：

  • name
  • fixed
  • default

# 5.4.1. name

(必填) 保留参数的名称。 始终以 _ 开始。

允许的值： _type, _path 或 _times

# 5.4.2. fixed fixed

(可选) 保留参数的固定值(即不可覆盖)。

# 5.4.3. 5.5.3. default

(可选) 保留参数的默认值。 当没有提供值时使用。

# 5.5. 5.5. parameters

info (可选）指定Airnode终端节点参数的对象列表，这些参数映射到特定的API操作的参数。 每个对象都有以下元素：

  • operationParameter
  • name
  • default
  • description
  • require
  • example

# 5.5.1. 5.5.1. operationParameter

必须是四个可能的值之一(query, header, path, cookie)。

  • name
  • in
# 5.5.1.2. in name

从 API 操作中的参数名称。

# 5.5.1.2. in

Must be one of four possible values (query, header, path, cookie).

# 5.5.2. name name

(必填) Airnode 节点参数的名称。 不允许以 _ 开始。

# 5.5.3. default

(可选) Airnode 节点参数的默认值。 当没有提供值时使用。

# 5.5.4. description *

(可选) 是否需要Airnode 节点参数，布尔值。

# 5.5.5. 5.5.5. required

(可选) 用于测试调用的示例值。

# 5.5.6. 5.5.6. example

(可选) Airnode 终端节点意图的一句话摘要。

# 5.6. 5.6. summary *

（可选）Airnode 终端节点外部文档的 URL。

# 5.7. 5.5.4. description *

请注意

# 5.8. 5.8. externalDocs *

由 (*) 表示的字段用于文档目的，不被Airnode使用。

Please Note

Fields denoted by * are for documentation purposes and not used by Airnode node.

Last Updated: 5/9/2022, 3:28:29 PM

← 保留参数 →