平安云 - 云以致用智造未来

创建API

本文主要介绍如何创建API。  前提条件 1.  您已成功创建API分组，可参考<a href="https://pinganyun.com/ssr/help/middleware/APIGateway/Instance_Management.Publishing_API.Group_Management.Create_Group" target="_blank">创建分组</a>。 2.  若定义API请求的后端服务类型选择VPC通道，请先创建VPC通道，可参考<a href="https://pinganyun.com/ssr/help/middleware/APIGateway/Instance_Management.Publishing_API.VPC_Connection.Create_VPC_Connection" target="_blank">创建VPC通道</a>。 注意事项 每个分组最多可创建100个API。 操作步骤 1.  登录<a href="https://pinganyun.com/console/apiGateway" target="_blank">API网关管理控制台</a>。 2.  单击左侧导航栏开放API > API管理，进入API管理页面。 3.  选择目标地域。 4.  单击页面右上角的创建，进入创建API页面。 基本信息 1.  填写创建API的基本信息： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> API名称 </td> <td> API的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />： 1.  API名称在当前主账户的每个地域下必须唯一。 2.  API名称的长度为2~50个字符。 3.  可包含汉字、英文、下划线_、或数字。 4.  需要以英文或汉字开始。 </td> </tr> <tr> <td> 所属分组 </td> <td> 选择已成功创建的分组。 </td> </tr> <tr> <td> 类型 </td> <td> API的类型，目前支持： •  公开：在release环境发布的API，可以发布到云市场。 •  私有：不会发布到云市场。如果用户调用私有类型的API，需要进行授权。 </td> </tr> <tr> <td> 安全认证 </td> <td> 调用API的认证方式，确保调用方发送给API网关的API请求的安全性，目前支持： •  APP认证：调用API时，由平安云API网关服务负责对应用进行安全认证。 •  无认证：不需要认证。任何可以获取此API的应用，均可以调用。 </td> </tr> <tr> <td> 签名算法 </td> <td> 在安全认证为APP认证时，需要设置此项。目前支持： •  HmacSHA1 •  HmacSHA256 </td> </tr> <tr> <td> 描述 </td> <td> API的描述信息。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：描述信息长度为1~200个字符。 </td> </tr> </tbody> </table> 2.  单击下一步。 定义API请求 1.  根据以下信息，定义API请求的相关信息： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 请求PATH </td> <td> API的请求路径，例如：/getUserInfo/{userId}。 如果请求Path中包含参数： •  请用{ }标识参数，参数区分大小写。 •  需要对参数进行定义，可参考<a href="#id_01" target="_blank">入参定义</a>。 </td> </tr> <tr> <td> 匹配模式 </td> <td> API请求路径的匹配模式，目前支持： •  完整路径匹配：调用的请求路径需要与请求PATH完全一致。 •  前缀路径匹配：调用的请求路径以请求PATH为前缀。 例如：定义API请求时设置的请求PATH是/getUserInfo/test，使用前缀路径匹配时，可通过/getUserInfo/test/AAA访问，但不可通过/getUserInfo/testAAA访问。 </td> </tr> <tr> <td> HTTP Method </td> <td> 接口的调用方式，目前支持：GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY </td> </tr> <tr> <td> 支持跨域 </td> <td> 是否开启跨域（CORS：Cross-Origin Resource Sharing），可参考<a href="https://pinganyun.com/ssr/help/middleware/APIGateway/Common_Reference.CORS.Classify" target="_blank">跨域资源共享（CORS）</a>。 默认情况下不开启跨域。 </td> </tr> <tr> <td> 入参定义 </td> <td> 若请求路径中包含参数，需要对该参数进行详细定义。 在入参定义区域，单击添加，进入添加入参定义页面<a href="#id_01" target="_blank">添加入参定义</a>。 </td> </tr> <tr> <td> 请求体内容描述 </td> <td> 请求体的相关描述。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />： 1.  在HTTP Method是POST、PUT、PATCH或ANY时，此项可填。 2.  描述信息长度为0~512个字符。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_01" name="id_01">入参定义</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 参数名 </td> <td> 参数的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：参数的名称需要与请PATH中设置的参数名称一致。 </td> </tr> <tr> <td> 参数位置 </td> <td> 参数在请求路径中的位置，目前支持：PATH、QUERY、HEADER。 </td> </tr> <tr> <td> 类型 </td> <td> 参数字段的数据类型，目前支持：String、Int、Long、Float、Double、Boolean。 </td> </tr> <tr> <td> 是否必填 </td> <td> 调用API时，此参数是否必须填写。 如果必填，API网关在将校验API请求是否包含此参数，如果检测没有此参数，则拒绝该请求。 参数位置是： •  PATH时，默认必填，不可修改。 •  QUERY时，默认必填，可修改。 •  HEADER时，默认必填，可修改。 </td> </tr> <tr> <td> 默认值 </td> <td> 是否必填选择否时，此项可设置。 在API请求不包含此参数时，API网关将自动为该参数增加设置的默认值发送给后端服务。 </td> </tr> <tr> <td> 示例 </td> <td> （可选）填写参数值的示例。 </td> </tr> <tr> <td> 描述 </td> <td> （可选）对此参数的说明。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：描述信息长度为0~200个字符。 </td> </tr> </tbody> </table> 2.  单击下一步。 定义后端服务 定义后端服务主要是定义API网关控制台前端和后端服务的映射，用户请求到达API网关后，API网关会根据您的后端服务配置，将API请求发送给后端服务。 后端服务类型包括： <ul> <li>HTTP/HTTPS：若您的服务使用的是HTTP/HTTPS协议，可选择此项。</li> <li>MOCK：Mock方式主要用于API的调试环境，提前设置返回结果，在测试环境下调用API时，不调用后端服务，直接返回设置的结果给API调用方。</li> </ul> 1.  根据以下信息，定义后端服务： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 后端服务类型 </td> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td rowspan="7"> HTTP/HTTTPS </td> <td> HTTP Method </td> <td> 接口的调用方式，目前支持：GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY。 </td> </tr> <tr> <td> 后端服务地址 </td> <td> 后端服务的地址，格式：http(s)://host:port。 例如：http://10.0.0.1或http://autotest.com.cn <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />： • host：后端服务的IP地址或访问域名。 •  （可选）port：后端服务的访问端口。 •  后端服务地址支持环境变量，需用[ ]标识，例如：http://api.[url].com，环境变量可参考<a href="https://pinganyun.com/ssr/help/middleware/APIGateway/Instance_Management.Publishing_API.Group_Management.Environment_Variable" target="_blank">添加环境变量</a>。 </td> </tr> <tr> <td> 后端请求Path </td> <td> 后端服务的请求路径。 一个API中的请求PATH对应一个后端服务请求Path。 •  可包含参数，用{ }标识。同时需要对参数进行定义，可参考后端服务参数。 •  可包含环境变量，用[ ]标识，例如：http://api.[url].com，环境变量可参考<a href="https://pinganyun.com/ssr/help/middleware/APIGateway/Instance_Management.Publishing_API.Group_Management.Environment_Variable" target="_blank">添加环境变量</a>。 </td> </tr> <tr> <td> 后端Socket超时 </td> <td> 后端服务请求超时的时间，超过设定值后，API网关不再等待后端服务的响应，同时返回相应的错误信息到API调用方。取值范围是1~60000ms，默认情况是5000ms。 </td> </tr> <tr> <td> 后端服务参数 </td> <td> 如果后端请求Path中包含参数，需要对该参数进行详细定义。 在后端服务参数区域，单击添加，进入添加后端参数映射页面添加相关参数，可参考<a href="#id_02" target="_blank">添加后端服务参数</a>。 </td> </tr> <tr> <td> 常量参数 </td> <td> 常量参数对用户不可见，如果配置了常量参数，API网关会在转发API请求时，将常量参数加入到请求中的指定位置，传递至后端服务，从而实现后端的业务需求，可参考<a href="#id_03" target="_blank">添加常量参数</a>。 </td> </tr> <tr> <td> 系统参数 </td> <td> 系统参数对用户不可见，如果配置了系统参数，API网关会将系统参数加入到请求中的指定位置，传递至后端服务，从而实现后端的业务需求，可参考<a href="#id_04" target="_blank">添加系统参数</a>。 </td> </tr> <tr> <td rowspan="2"> Mock </td> <td> Mock返回结果 </td> <td> 以Mock方式调用API返回的结果。 </td> </tr> <tr> <td> Mock响应头 </td> <td> 定义Mock响应头的参数名和参数值，用于请求后端服务。 在Mock响应头区域，单击添加，进入添加Mock响应头页面添加Mock响应头的相关信息，可参考<a href="#id_05" target="_blank">添加Mock响应头</a>。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_02" name="id_02">后端服务参数</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 入参名称 </td> <td> 选择入参的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：此处的入参是请求PATH中设置的参数。 </td> </tr> <tr> <td> 入参位置 </td> <td> 入参的位置。 默认是请求PATH中入参的位置，不可修改。 </td> </tr> <tr> <td> 入参类型 </td> <td> 入参字段的数据类型。 默认是请求PATH中入参的类型保持，不可修改。 </td> </tr> <tr> <td> 后端参数位置 </td> <td> 后端参数的位置，目前支持：PATH、QUERY及HEADER。 </td> </tr> <tr> <td> 后端参数名称 </td> <td> 后端参数的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：参数名称需要与后端请求Path中设置的参数名称一致。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_03" name="id_03">常量参数</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 参数名 </td> <td> 常量参数的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />： •  常量参数的名称长度为1~50个字符。 •  可包含英文字母和数字。 •  首字符必须是英文字母。 </td> </tr> <tr> <td> 参数位置 </td> <td> 常量参数的位置，目前支持：PATH、QUERY及HEADER。 </td> </tr> <tr> <td> 参数值 </td> <td> 常量参数的取值。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：支持大小写字母、数字以及特殊字符（-._~!$&'()*+,;=:@）。 </td> </tr> <tr> <td> 描述 </td> <td> 常量参数的描述信息。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />：描述信息长度为0~200个字符。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_04" name="id_04">系统参数</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 参数名 </td> <td> 选择目标系统参数。 </td> </tr> <tr> <td> 参数说明 </td> <td> 对所选系统参数的解释。 </td> </tr> <tr> <td> 参数位置 </td> <td> 系统参数的位置，目前支持：PATH、QUERY及HEADER。 </td> </tr> <tr> <td> 后端参数名称 </td> <td> 后端参数的名称，与系统参数名称进行映射。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20192910173558-17d8d04f9e75.png" style="height:26px; margin:0px; width:65px" />： •  系统参数的名称长度为1~50个字符。 •  可包含英文字母和数字。 •  首字符必须是英文字母。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_05" name="id_05">Mock响应头</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; width:57px"> 配置项 </td> <td style="background-color:#ededed; width:730px"> 说明 </td> </tr> <tr> <td style="width:57px"> 参数名 </td> <td style="width:730px"> Mock响应头的参数名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104134-169a4a6d94c9.png" style="height:26px; margin:0px; width:65px" />：支持英文字母（区分大小写）、数字、特殊字符（!#$%&'*+-.^_`|~）。 </td> </tr> <tr> <td style="width:57px"> 参数值 </td> <td style="width:730px"> Mock响应头的参数取值。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104134-169a4a6d94c9.png" style="height:26px; margin:0px; width:65px" />：支持ASCII中所有可见字符（\x21~\x7E），中间字符支持空格（SP）或者水平制表符（HTAB）。 </td> </tr> </tbody> </table> 2.  单击下一步。 定义返回结果 1.  根据以下信息，定义返回结果： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 返回Content-type </td> <td> 选择返回结果的内容类型。目前支持： <ul> <li>application/json;charset=utf-8：JSON格式。</li> <li>text/plain;charset=utf-8：纯文本格式。</li> <li>application/octet-stream;charset=utf-8：二进制流格式。</li> <li>application/xml;charset=utf-8：XML解析格式。</li> <li>text/html;charset=utf-8：HTML解析格式。</li> <li>passthrough：透传Content-type。</li> </ul> </td> </tr> <tr> <td> 成功返回结果示例 </td> <td> 调用API成功，返回的响应结果。 </td> </tr> <tr> <td> 失败返回结果示例 </td> <td> 调用API失败，返回的响应结果。 </td> </tr> <tr> <td> 错误码定义 </td> <td> 可根据业务的实际情况设置错误代码，作为排查报错信息的索引。 在错误码定义区域，单击添加，进入添加错误码页面添加错误码的相关信息，可参考<a href="#id_06" target="_blank">添加错误码</a>。 </td> </tr> </tbody> </table> 根据以下信息，添加<a id="id_06" name="id_06">错误码</a>，并单击确认： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed"> 配置项 </td> <td style="background-color:#ededed"> 说明 </td> </tr> <tr> <td> 错误码 </td> <td> 错误码的名称。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104134-169a4a6d94c9.png" style="height:26px; margin:0px; width:65px" />： <ul> <li>名称的长多为1~50个字符。</li> <li>可包含英文、数字、中划线-、英文点.及下划线_。</li> </ul> </td> </tr> <tr> <td> 错误信息 </td> <td> 错误的详细信息。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104134-169a4a6d94c9.png" style="height:26px; margin:0px; width:65px" />：描述信息的长度为1~50个字符。 </td> </tr> <tr> <td> 描述 </td> <td> 错误码的描述信息。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104134-169a4a6d94c9.png" style="height:26px; margin:0px; width:65px" />：描述信息的长度为0~200个字符。 </td> </tr> </tbody> </table> 2.  单击完成。 执行结果 系统打印提示信息。 <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104124-1caffbb2997c.png" style="height:221px; width:524px" /> <ul> <li>单击发布API，进入发布API页面，进行API发布的配置，可参考发布API。</li> <li>单击API详情，进入API详情页面，查看API的详细信息，可参考查看API。</li> <li>单击确认，可在API管理页面的目标地域下，看到刚刚创建的API。</li> </ul> <img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010104107-13393777983d.png" style="height:54px; width:830px" /> 后续操作 在API管理页面的目标地域下，单击目标API操作列的编辑，进入编辑API页面，可对API的配置信息进行修改。

以上内容是否解决了您的问题？是否