1 概述

阅读对象

  • 云市场合作伙伴,希望将自己的API上架到到云市场上进行售卖。

在完成服务商入住API集市后,API商品上架过程分成两个步骤

  • 步骤一:在API网关上进行API的配置,并发布在API网关上;
  • 步骤二:在云市场服务商控制台上进行API商品的配置,包括商品介绍、售卖信息等。

本文目标

  • 帮助合作伙伴快速了解API商品的构成,以案例的方式了解步骤一的主要操作过程,特别是和API商品紧密相关的内容;
  • 本文案例中不涉及更多的API配置方式,具体可详见API网关的其他相关文档。

2 API商品的构成

客户在云市场上浏览API商品的时候,会看到API商品主要有三部分构成,如下例所示:

a. 商品简介和售卖信息

b. API接口的信息

c. 商品的更多信息,包括产品亮点、产品说明、产品价格、评论、使用指南等。

上面的三部分,其中(a)和(c)是需要云市场的服务商控制台中进行配置,(b)里面是需要在API网关上进行配置。 一个API商品里面可以包含多个API,在上图的示例中,该API商品只有一个API。

3 API网关上配置并发布API

3.1 概述

注意:需要使用入住成功后的服务商账号在API网关上进行配置,否则在云市场服务商控制台上将无法获取到配置好的API信息。

以下图的API商品为例,介绍如何在API网关上进行配置。

3.2 创建API分组

首先需要在API网关中创建分组,API网关的一个API分组对应的是云市场上的一个API商品。如下图所示,在华东1创建了一个API分组。

注意事项:

  • 如何选择Region。建议根据API后端服务所在地理位置就近选择。如果API的后端是函数计算或者是在阿里云的VPC内,则需要在同一个Region内。您在云市场服务商控制台上创建API商品时,也需要先选择对应的Region,然后才能选择到API分组,如下图所示。

  • API分组的实例类型建议选择"共享实例(VPC)";
  • API分组的名称、描述信息等,都可以根据您的需要随意设置,不会影响到最终用户看到的API商品信息。

3.3 配置API

对应这个API商品,需要在这个分组下创建两个API,如下图所示:

下面章节以"测试商品的API_1"为例,具体展开如何进行配置。

3.3.1 API基本信息

配置API基本信息,如下图所示:

注意事项:

  • API名称,设置后将会显示在API商品页中,如下图所示。商品上架后,API名称也可以修改;

  • 安全认证,需要选择"阿里云APP";
  • AppCode认证,需要选择"上架云市场后开启";在商品页中,最终用户可以使用两种方式( API简单身份认证调用方法APPCode、API签名认证调用方法APPKey&APPSecret )进行调用。关于阿里云APP的这两种认证方式的区别可详见阿里云APP 阿里云APP认证说明
  • 注意一定要选择"API选项"中的"允许上架云市场",否则此API在商品页中将无法看到。

3.3.2 定义API请求

定义API请求,如下图所示:

注意事项:

  • 非WEBSOCKET的API,协议请选择"HTTPS";
  • 二级域名为API网关自动分配,无需进行调整;
  • 请求Path、HTTP Method、入参请求模式,您可根据API及后端服务的情况来进行设置,本例中HTTP Method选择的POST,其他的使用默认值;
  • 入参定义,本例中配置了三种不同位置的参数,同时配置了默认值、示例和描述,商品发布后,入参信息会在商品页中的如下位置出现:

3.3.3 定义API后端服务

这部分用于配置API网关如何访问后端服务,相关信息都不会出现在API商品信息中,更多配置请详见API网关帮助文档。

3.3.4 定义返回结果

定义返回结果,如下图所示。建议您填写"返回结果示例"、"失败返回结果示例"、"错误码定义",可以帮助最终使用者在API商品页中更好的了解如何使用接口,同时也能大大减少您的支持工作量。

完成此部分的配置后,会在商品页中如下位置出现。

3.3.5 添加示例代码

在API商品上,除了上述过程中对接口的输入和输出的各种描述之外,还强烈建议您完善示例代码,既能提高用户体验,也能有效降低您的的支持工作量。API网关会先根据您的API配置信息自动生成一份默认的示例代码,如下图所示:

配置完成后,在API商品页中如下位置显示:

注意事项:

  • 示例代码仅适用于采用APPCode的认证方式调用;
  • 由于是自动生成,因此会存在一定的局限性。如一些场景(如OCR类商品),输入参数中需要传入base64之后的图片文件内容,示例代码当前无法自动生成对应的代码片段,建议您可以根据商品特点在自定义示例代码中直接进行编辑,以补充对应的代码;
  • 如果您对示例代码进行过编辑,后续即使API参数发生变化,API网关也不会覆盖您的示例代码,请注意及时更新。

3.4 发布和调试API

API配置完成后,需要发布到环境中才可进行调试、调用,在本例中直接发布到了"线上"环境中,更多关于API网关的环境管理的内容可以详见 环境管理

发布完成后,由于API的认证方式是"阿里云APP",因此需要在应用管理菜单中创建一个调试用的APP,如下图:

需要在API的授权信息 菜单中,为此API添加授权,授权成功后如下图所示:

最后可以在API调试菜单中进行参数的调试确认,如下图所示:

注意事项:

  • 除了在调试API的页面中进行调试之外,为了保证最终发布的API的准确性,还请您通过代码调用API进行测试。如何使用"阿里云APP"认证方式进行调用,您可以使用SDK的方式或自行实现阿里云APP加签算法,详见 加签算法
  • 您可以使用这个分组自动创建的公网二级域名进行调用测试,同时也需要了解到直接使用公网二级域名进行调用时有比较大的局限性,具体可以详见分组详情的页面。

3.5 API商品的域名

在使用API网关进行API全生命周期管理的场景中,您需要在分组上绑定您的正式域名后,业务系统、客户端程序才能正式调用这些发布的API。但针对这些准备上架到云市场的API分组,则不必您绑定域名,在云市场服务商控制台中,发布商品的时候,只需要您配置三级域名即可,如下图。最终用户在云市场购买成功后,就可以通过此域名访问到您的API商品。

注意事项:

  • 在云市场服务商控制台上发布API商品时,需要您填写的前缀要保证全局唯一;
  • 商品发布后,此域名将会自动绑定到API网关的这个分组上,如下图所示,请您务必不要删除此域名,或绑定其他域名,否则都可能会造成您发布的API商品无法访问,给最终用户带来使用困扰。

4. 发布API商品

详见云市场相关文档