全部产品

创建 API

更新时间:2018-12-19 18:07:07

创建 API 即录入 API 的定义,需要录入 API 的基本信息、服务信息、请求信息、和返回信息,然后对创建的 API 进行调试,及进行安全配置。经测试证明 API 可用后,可发布上线供用户使用。

定义 API

API 网关控制台API 列表 页面,单击 创建 API,即进入 API 的创建和定义流程。

第一部分:定义请求的基本信息

API 基本信息包括 API 分组、 API 名称、安全认证方式、 API 类型、和描述。

  • API 分组:分组是 API 的管理单元。创建 API 之前,您需要先创建分组( API 分组的详细说明见 API 开放)。
  • API 名称:API 名称标识需在所属分组内具有唯一性。
  • 安全认证方式:是 API 请求的认证方式,目前支持 阿里云APPOpenID ConnectOpenID Connect & 阿里云APP无认证 四种认证方式。

    • 阿里云APP:要求请求者调用该 API 时,需通过对 APP 的身份认证。

    • OpenID Connect:是一套基于 OAuth 2.0 协议的轻量级规范,提供通过RESTful APIs 进行身份交互的框架。可以使用 OpenID Connect 和您的自有账号系统无缝对接。详细介绍请参见 OpenID Connect

    • OpenID Connect & 阿里云APP:同时进行OpenID Connect和阿里云APP认证。

    • 无认证:即任何人知晓该 API 的请求定义后,均可发起请求,网关不对其做身份验证,均会将请求转发至您的后端服务。(强烈不建议使用此模式。)
  • API 类型:分为 公开私有 两种。

    • 公开 类型的 API:所有用户均可以在 API 网关控制台,已发布 API 页面看到 API 的部分信息。公开 类型的 API 会跟随 API 分组上架到云市场,供用户购买和调用。

    • 私有 类型的 API:不能上架到云市场中售卖。如果有用户想要调用您的私有类型的 API ,需要您主动操作授权,否则用户无渠道获取 API 信息。

  • 描述: API 功能描述。

第二部分:定义 API 请求

这部分是定义用户如何请求您的 API ,包括协议、请求Path、HTTP Method、入参请求模式、和入参定义。

  • 协议:支持 HTTP 和 HTTPS 协议。

  • 请求Path:Path 指相对于服务 Host, API 的请求路径。请求 Path 可以与后端服务实际 Path 不同,您可以随意撰写合法的有明确语义的 Path 给用户使用。您可以在请求 Path 中配置动态参数,即要求用户在 Path 中传入参数,同时您的后端又可以不在 Path 中接收参数,而是映射为在 Query、Header 等位置接收。在 开放 API 接入 API 网关 中,有详细的举例说明和操作截图展示。

  • HTTP Method:支持标准的 HTTP Method,可选择 PUT、GET、POST、DELETE、PATCH、或 HEAD。

  • 入参请求模式:API 网关对入参的处理模式,支持 入参映射入参透传 两种模式。

    • 入参映射:即 API 网关在接收到您的 API 请求时,通过映射关系将请求转换成您后端需要的格式。

      使用入参映射模式的特点:

      • 定义方式:定义此类 API 时,需添加前后端参数映射关系。

      • 使用场景:

        • 同一接口,在 API 网关定义不同的 API,以服务差异化的用户。

        • 通过 API 网关规范化陈旧的系统接口。

      • 实现功能:

        • 支持您配置前端和后端的全映射,即参数混排。可以让 API 用户在 Query 中传入参数, 后端从 Header 里接收等。

          支持:参数名称转换和参数位置转换。

        • 可以定义参数的校验规则,实现请求参数的预校验,降低后端处理非法请求的压力。

          支持:参数长度校验、参数数值大小校验、参数正则校验、和参数 JSON Schema 校验。

    • 入参透传:即 API 网关在接收到 API 请求后,不对请求进行处理,直接转发到后端服务。此模式下:

      • 无法实现参数校验。

      • 无法生成详细的 API 调用文件。

      • 自动生成的 SDK 不包含请求入参。

  • 入参定义:定义您 API 的请求入参,包含参数名、参数位置、类型、是否必填、默认值、示例、描述等信息。入参透传模式下,不需要录入参数

    • 参数名:展示给用户的参数名称。

    • 参数位置:参数在请求中的位置,包含 Head、Query、和 Parameter Path。

      注意:如果您在 Path 中配置了动态参数,存在参数位置为 Parameter Path 的同名参数。

    • 类型:字段的类型,支持:String、Int、Long、Float、Double、和 Boolean。

    • 必填:指此参数是否为必填。当选择为 时,API 网关会校验用户的请求中是否包含了此参数。若不包含此参数,则拒绝该请求。

    • 默认值:当 必填 时生效。在用户请求中不包含此参数时,API 网关自动添加默认值发送给后端服务。

    • 示例:指参数的填写示例。

    • 描述:参数的用途描述及使用注意事项等。

    • 参数校验规则:单击 编辑更多 配置校验规则,如参数值的长度、取值大小、枚举、正则、JSON Schema等。API 网关会参照校验规则对请求做初步校验。如果入参不合法,则不会发送给您的后端服务,以降低后端服务的压力。

第三部分:定义后端服务信息

这部分主要是定义一些参数的前后端映射,即 API 后端服务的配置,包括后端服务地址、后端Path、后端超时时间、参数映射、常量参数、系统参数。用户请求到达 API 网关后,API 网关会根据您的后端配置,映射为对应的后端服务的请求形式,请求后端服务。

  • 后端服务类型:目前支持 HTTP/HTTPS和函数计算两种类型。

    • HTTP/HTTPS:若您的服务为 HTTP/HTTPS 服务,则选择此项。

      注意:若是 HTTPS 服务,后端服务必须有 SSL 证书。

    • 函数计算:若选择函数计算为后端服务,需先在 函数计算控制台 中创建函数,并需填入函数服务名称和函数名称,和获取函数计算角色 Arn。

  • VPC 通道:当您的后端服务在 VPC 中时,需要选择 使用 VPC 通道。使用方法,请参见 专属网络 VPC 环境开放 API

  • 后端服务地址:后端服务的 Host,可以是一个域名,也可以是 http(s)://host:port 的形式。填写时,必须包含 http:// 或 https:// 。

  • 后端请求 Path:Path 是您的 API 服务在您后端服务器上的实际请求路径。若您后端 Path 需要接收动态参数,则需要声明调用者需传入参数的具体位置和参数名,即声明映射关系。

  • 后端超时时间:指 API 请求到达 API 网关后,API 网关调用 API 后端服务的响应时间,即由 API 网关请求后端服务开始直至 API 网关收到后端返回结果的时长。单位为毫秒。设置值不能超过 30 秒。如果响应时间超过该值,API 网关会放弃请求后端服务,并给用户返回相应的错误信息。

  • 常量参数:您可以配置常量参数。您配置常量参数对您的用户不可见,但是 API 网关会在中转请求时,将这些参数加入到请求中的指定位置,再传递至后端服务,实现您的后端的一些业务需求。比如,您需要 API 网关每次向后端服务发送请求都带有一个关键词 aligateway,您就可以把 aligateway 配置为常量参数,并指定接收的位置。

  • 系统参数:指 API 网关的系统参数。默认系统参数不会传递给您,但是如果您需要获取系统参数,您可以在 API 里配置接收位置和名称。具体内容如下表:

    参数名称 参数含义
    CaClientIp 发送请求的客户端 IP
    CaDomain 发送请求的域名
    CaRequestHandleTime 请求时间(格林威治时间)
    CaAppId 请求的 APP 的 ID
    CaRequestId RequestId
    CaApiName API 名称
    CaHttpSchema 用户调用 API 使用的协议,http 或者 https
    CaProxy 代理(AliCloudApiGateway)

    注意:您需确保您录入的所有参数的参数名称全局唯一,包括 Path 中的动态参数、Headers 参数、Query 参数、Body 参数(非二进制)、常量参数、系统参数。如果您同时在 Headers 和 Query 里各有一个名为 name 的参数,将会导致错误。

第四部分 定义返回结果

录入返回 ContentType、返回结果示例、失败返回结果示例、和错误码定义。

API调试

API 定义录入完成后,您可以在 API 调试页面调试 API,以确定 API 的可用性。

API 创建、定义完成后,页面自动跳转到 API 列表 页。您可以通过此页面按钮,测试创建的 API 是否可用,请求链路是否正确。

  1. 单击 API 名称或 管理 按钮,进入 API 定义 页面。

  2. 单击左侧导航栏中 调试 API

  3. 输入请求参数,单击 发送请求

    返回结果将显示在右侧页面。

    如果调试返回成功结果,则说明该 API 可以使用。

    如果返回代码为 4XX 或 5XX,则表示存在错误。请参见 如何获取错误信息错误代码表

后续步骤

完成以上定义后和初步调试后,您就完成了 API 的创建。您可以发布 API 到测试、预发、线上环境,继续调试或供用户使用。还可以为 API 绑定 签名密钥流量控制 等安全配置。