DocsICP FilingConsole
Documentation

ImportHttpApi - 导入HTTP API

Updated at:
Copy as MD
Product
My Favorites

导入HTTP API，支持将OpenAPI 2.0和 OpenAPI 3.0.x版本的定义文件导入为REST类型的API。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

apig:ImportHttpApi

none

*全部资源

*

 无 无

请求语法

POST /v1/http-apis/import HTTP/1.1

请求参数

名称

类型

必填

描述

示例值
body

object

否

请求体参数。

{'key': 'value'}
specContentBase64

string

否

Bse64 编码的 API 定义，支持 OAS2.0 和 OAS3.0 规范，支持 YAML 格式和 JSON 格式。优先级高于 specFileUrl 参数。 若文件大小超过 10MB 请使用 specFileUrl 参数传递。

b3BlbmFwaTogMy4wLjAKaW5mbzoKICAgIHRpdGxlOiBkZW1vCiAgICBkZXNjcmlwdGlvbjogdGhpc2lzZGVtbwogICAgdmVyc2lvbjogIiIKcGF0aHM6CiAgICAvdXNlci97dXNlcklkfToKICAgICAgICBnZXQ6CiAgICAgICAgICAgIHN1bW1hcnk6IOiOt+WPlueUqOaIt+S/oeaBrwogICAgICAgICAgICBkZXNjcmlwdGlvbjog6I635Y+W55So5oi35L+h5oGvCiAgICAgICAgICAgIG9wZXJhdGlvbklkOiBHZXRVc2VySW5mbwogICAgICAgICAgICByZXNwb25zZXM6CiAgICAgICAgICAgICAgICAiMjAwIjoKICAgICAgICAgICAgICAgICAgICBkZXNjcmlwdGlvbjog5oiQ5YqfCiAgICAgICAgICAgICAgICAgICAgY29udGVudDoKICAgICAgICAgICAgICAgICAgICAgICAgYXBwbGljYXRpb24vanNvbjtjaGFyc2V0PXV0Zi04OgogICAgICAgICAgICAgICAgICAgICAgICAgICAgc2NoZW1hOiBudWxsCnNlcnZlcnM6CiAgICAtIHVybDogaHR0cDovL2FwaS5leGFtcGxlLmNvbS92MQo=
specFileUrl

string

否

API 定义文件的下载地址，需要公网可以下载或使用相同 region 的 OSS 内网下载地址。文件地址要求拥有下载权限，对于 OSS 非公开读的文件链接，请参考文档使用预签名 URL 下载文件，填写带有下载权限的地址。目前仅支持 OSS 上存储的 API 定义文件。

https://bucket.oss-cn-hangzhou.aliyuncs.com/**/*.yaml
name

string

否

导入的 API 名称，若不填则从 API 定义文件中提取。若 API 名称与版本化配置已存在，则本次导入会根据 strategy 字段对已有 API 定义做更新。

import-test
description

string

否

导入的 API 描述字段，若未填写则从 API 定义中提取。限制长度 255 字节。

测试专用API
versionConfig HttpApiVersionConfig

否

API 版本化配置，若开启版本化配置，则版本号 API 名称与已存在 API 相同时，本次导入将视为更新动作。若未开启版本化配置，则 API 名称与已存在 API 相同时，本次导入将视为更新动作。

dryRun

boolean

否

导入预检，若开启则仅进行检测，不进行导入动作。

false
strategy

string

否

当导入的 API 名称与版本管理与已存在 API 相同时，需要指定更新策略。

  • SpecOnly：完全以导入文件为准。

  • SpecFirst：以导入文件为优先，新增接口与更新已有接口，文件中未提及的接口保持不动。

  • ExistFirst：以存在的 API 为优先，只新增接口，不更新已有接口。 为空时默认 ExistFirst 策略。

枚举值：

  • SpecFirst :

    以导入文件为优先，新增接口与更新已有接口，文件中未提及的接口保持不动

  • SpecOnly :

    完全以导入文件为准

  • ExistFirst :

    以存在的 API 为优先，只新增接口，不更新已有接口

ExistFirst
withGatewayExtension

boolean

否

是否导入网关扩展信息

false
targetHttpApiId

string

否

若指定该字段，则本次导入将更新指定 API 而非导入或根据 API 名称与版本管理配置搜索已存在 API。目标 API 必须是 REST 类型。

api-xxxx
resourceGroupId

string

否

资源组 ID。

rg-aek23nsa353vmra
specOssConfig

object

否

OSS 信息。

regionId

string

否

地域 ID。

cn-shanghai
bucketName

string

否

bucket 名称。

gms-service-prod
objectKey

string

否

文件完整路径。

/test/swagger.json
deployConfigs

array

否

API 部署配置。

HttpApiDeployConfig

否

参数

mcpRouteId

string

否

MCP 路由 ID。

xxx
gatewayId

string

否

网关 ID。

gw-xxx

返回参数

名称

类型

描述

示例值

object

响应。

requestId

string

请求 ID。

CE857A85-251D-5018-8103-A38957D71E20
code

string

响应状态码。

Ok
message

string

响应消息。

success
data

object

API 信息。

name

string

API 名称。

import-test
httpApiId

string

HTTP API 唯一 ID。

api-xxx
dryRunInfo

object

预检结果。

successOperations

array<object>

预检成功的接口列表。

object

接口信息。

action

string

预检后将执行的动作。

  • Create：创建。

  • Update: 更新。

枚举值：

  • Create :

    Create

  • Update :

    Update

Create
name

string

接口名称。

CreateUser
path

string

接口路径。

/v1/users
method

string

接口方法。

POST
failureOperations

array<object>

预检失败的接口列表。

object

接口信息。

path

string

接口路径。

/v1/orders
method

string

接口方法。

GET
errorMessage

string

错误信息

缺少响应定义。
successComponents

array<object>

预检成功的数据结构列表。

object

数据结构信息。

action

string

预检后将执行的动作。

  • Create：创建。

  • Update: 更新。

枚举值：

  • Create :

    Create

  • Update :

    Update

Create
name

string

数据结构名称。

userDTO
failureComponents

array<object>

预检失败的数据结构列表。

object

数据结构信息。

name

string

数据结构名称。

orderDTO
errorMessage

string

错误信息。

数据结构定义有误。
successRoutes

array<object>

成功导入的路由列表

object

路由列表

action

string

操作类型

Create
name

string

名称

user-route
failureRoutes

array<object>

失败的路由列表

object

路由列表

name

string

参数名称。

admin-route
errorMessage

string

错误信息

conflict
errorMessages

array

错误信息，若错误信息非空，则无法成功导入 API。

string

单个错误信息。

OpenAPI 3.1.x 版本不支持。
warningMessages

array

告警信息，告警信息非空，则部分接口/数据接口可能导入不成功。

string

单个告警信息。

GET /v1/orders 参数定义不完整。
existHttpApiInfo HttpApiApiInfo

已存在的 API 信息。若该字段非空，则导入动作将更新该 API。

mcpToolsDefinition

string

MCP 工具定义信息

...

示例

正常返回示例

JSON格式

{
  "requestId": "CE857A85-251D-5018-8103-A38957D71E20",
  "code": "Ok",
  "message": "success",
  "data": {
    "name": "import-test",
    "httpApiId": "api-xxx",
    "dryRunInfo": {
      "successOperations": [
        {
          "action": "Create",
          "name": "CreateUser",
          "path": "/v1/users",
          "method": "POST"
        }
      ],
      "failureOperations": [
        {
          "path": "/v1/orders",
          "method": "GET",
          "errorMessage": "缺少响应定义。"
        }
      ],
      "successComponents": [
        {
          "action": "Create",
          "name": "userDTO"
        }
      ],
      "failureComponents": [
        {
          "name": "orderDTO",
          "errorMessage": "数据结构定义有误。"
        }
      ],
      "successRoutes": [
        {
          "action": "Create",
          "name": "user-route"
        }
      ],
      "failureRoutes": [
        {
          "name": "admin-route",
          "errorMessage": "conflict"
        }
      ],
      "errorMessages": [
        "OpenAPI 3.1.x 版本不支持。"
      ],
      "warningMessages": [
        "GET /v1/orders 参数定义不完整。"
      ],
      "mcpToolsDefinition": "..."
    }
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。