小窍门
横看成岭侧成峰——ProtoPie Connect API 插件适用情形深度解析
这项功能给原本封闭的原型设计和交互设计带来了连接动态数据及具备接入外部逻辑的能力，使原型设计和交互设计的边界得到了前所未有的延申。
ProtoPie
April 22, 2024
ProtoPie Connect 中的 API 插件一经推出，深受用户赞誉与好评。这项功能给原本封闭的原型设计和交互设计带来了连接动态数据及具备接入外部逻辑的能力，使原型设计和交互设计的边界得到了前所未有的延申。
ProtoPie Connect 的 API 插件实际上是一个介于原型与 API 之间的代理访问器，在原型与 Connect 之间采用 Socket.io 协议消息实现通信，在 API 接口网站与 Connect 之间采用 http(s) 协议实现通信，这样就充分实现了原型与 API 之间的转译跨接，使得原型里的输入信息能被传输给 API、API 上返回的信息能在原型上进行显示。
在 API 插件的使用过程中，我们收到了许多关于判断是否适用的疑问。互联网上的各类 API 开放平台种类繁多，接入要求也各有不同，再加上企业内、软件开发部门等给出的 API 接入方式考虑了后端架构设计、安全接入要求等因素，常常使得设计师们虽然知道有 API 插件可用，但几经问询后又得知在接入方式无法适用的情形时有发生。
由此，我们将在本文中阐述如何在使用前根据 API 提供方给出的文档就能对 API 接口进行接入适用性判断，从而快速研判原型设计上是否可以使用 ProtoPie Connect 的 API 插件便捷地接入所需内容。
1. 检查 API 的调用协议
如同人与人之间的对话需要用双方都能听懂的语言来进行一样，进行 API 调用时，API 的提供方会指定某种协议来进行通信，而调用方（我们）需要遵守同样的调用协议，才能实现调用。
常见的 API 调用协议有:
- http 协议
- https 协议
- websocket 协议（通常会简写为 ws / wss 协议）
这其中只有 http 和 https 协议是 Connect API 插件可以调用的。
想要知道协议的种类，只需要查看文档中对连接地址的描述最前部
xxx:// 中的 xxx 部分是什么内容就可以知晓。- 例1：百度地图开放平台Web服务API下的普通IP定位功能，在文档最前部即可看到如下内容：
百度地图开放平台的普通 IP 定位 API
说明使用的是 https 协议，即可以使用 Connect API 插件进行访问。
- 例2：讯飞星火认知大模型的 Web API 接入，在文档的
1.1 请求地址部分可以看到如下内容：
星火认知大模型的 Web API
说明使用的是 websocket 协议，即不支持使用 Connect API 插件进行访问。
此外，一些接入平台仅提供 SDK 接入，不提供 Web API 接入时，显然也是无法直接使用 Connect API 插件来进行连接的：
- 例3：快手开放平台，在目录栏即可看到只支持 iOS 接入、Android 接入、网站应用接入以及服务端SDK：
快手开放平台
那么，这种情况下也是不支持 Connect API 进行接入的。
2. 检查 API 所支持的输入内容类型和格式
确认好对接所使用的协议后，下一步是确认 API 所需要的输入内容从 Studio 或 Connect 上能否提供。之所以要做这一步确认，是因为从 Studio 或 Connect 上只能提供文字类型及部分二进制类型的输入值。
具体来说，可能涉及向 API 接口进行输入的内容类型一般有：
- 文字类型（如关键词、经纬度、访问密钥等） ✅
- 图片类型
- 以URL格式表示的图片（如图片本身的网址） ✅
- 以二进制格式表示的图片（如 base64 编码的图片）⭕
- 音视频类型
- 以URL格式表示的音视频（如音视频文件本身的网址）✅
- 以网页承载表示的音视频（如哔哩哔哩上的一个页面，或网易云音乐上的一个页面） 🚫
- 以特定二进制格式表示的音视频（如以 pcm 编码的音频）🚫
在这些类型中，打✅的表示通常可以直接使用 Connect API 插件来进行接口调用。参看以下的两个例子。
- 例1：和风天气 API 实时天气功能，根据文档说明，要填写的参数均为文本类型：
和风天气 API 实时天气功能
location 参数和 key 参数均为文字类型，这种情况下就可以使用 Studio 或 Connect 将输入参数内容传到 API 接口上。
- 例2：百度智能云的植物识别API百度智能云的植物识别 API ()，在请求参数中可看到以下内容：
百度智能云的植物识别 API
这个 API 允许直接传入一个图片的 URL 来对这一图片进行识别，因此可以使用 Studio 或 Connect 将这个 URL 传到 API 接口上。
另一方面，在上面列举的内容类型中，标⭕的项即二进制格式表示的图片，可以通过第三方工具按照要求转为相应的编码格式后，将其编码存放到 Pie 的变量中，从而通过表达式的方式来将该内容发送到 Connect 上，继而发给相应的 API 接口。
参考上面的例2 ，请求参数中的 image 和 url 是择一输入的，如果选择使用的是 image参数，就需要先将图片转换为 base64 编码格式。这个操作可以通过
[在线图片 Base64 编码转换工具]之类的在线工具进行转换：
在线图片转 Base64 编码
转换后将上图中蓝框所示的转换结果全选并放置到文本类型的变量中，之后就可以用表达式来对这段内容进行拼接调用，从而实现输入到 API 接口上。
此外，上面列举的内容类型中，标🚫的项表示一般无法直接从 Studio / Connect 上进行 API 调用。
- 例3：百度 AI 百度AI开放平台的语音翻译API，在请求参数中可看到以下内容：
百度 AI 开放平台的语音翻译 API
在这个 API 接口中，voice 参数要求传入的是以 base64 编码的二进制数据，虽然也是采用看起来与上述图片编码类似的格式，但从技术原理来说，这一行为涉及到较复杂的技术分类处理情形，因此并不存在类似的在线转换网站，要实现将音频转为 base64 编码只能采用编程的方式进行。从而显然的就无法形成一个可存储的静态变量值来向 API 接口进行发送了。
3. 检查 API 是否强制要求动态内容输入
有时候一些比较关键、可能涉及重要权限、资金等的 API 接口上，我们可能会遇到在输入参数中需要给出诸如“签名”、“验签”、“摘要算法”、“时间戳”等信息的情形。如：
- 例1：淘宝开放平台查询appstore应用订购关系 API，在“公共请求参数”部分，可以看到如下内容：
淘宝开放平台查询appstore应用订购关系 API
由于此类 API 接口的操作可能会对资金发生直接或间接的影响，出于信息安全上的考量，关键 API 的访问往往被设计为需要一些动态信息来确保传输内容的及时性与完整性，这些动态信息就包括上述的“签名”、“时间戳”等内容，而且一般都是需要在 API 调用瞬间临时根据要传输的内容用编程的方式去生成的（所以才被称为“动态内容”）。因此在这种情况下，目前无法使用 Studio 或 Connect 对此类 API 进行调用。
4. 检查 API 的输入是否同时要求多个组成部分
如同大家在 Connect API 插件中所见到的填写项，一般来说，API 的输入参数可以包含在URL、Header、Body三部分中，API 接口方可能选取其中的一到三项并行地接收输入信息，而 Connect API 插件对于可变的内容（要使用消息值来传递的内容）只能通过覆写其中的一项来进行传递。因而造成了一些 API 接口不能直接使用 Connect API 插件进行访问，或需要采取一些变通的方法。
Connect API 插件中的填写项，包含三个部分
- 例1：百度千帆大模型平台的文心一言（ERNIE），其文档如下图所示：
百度千帆大模型平台的文心一言（ERNIE）API
显而易见，在调用这个 API 的时候，需要同时使用 Query（即 URL）项传输 access_token 并使用 Body 项传输 messages 等参数信息。使用 ProtoPie Studio 以消息形式调用时，只能覆写其中的一个，于是无法依照 API 设计者的期望灵活地调用这个 API 了。
但，这种情况下存在一个可以变通的办法——由于 access_token 是获取到之后30天内不需要变化的，因此可以按照文档中声明的、已经带上 access_token 的 URL 内容整体填写到 Connect API 插件的 URL 一栏中，再通过消息机制覆写和传输 Body 的内容。这种变通方式产生的缺陷在于：（1）每30天就需要更换 URL 中 access_token 的部分；（2）对他人共享这一访问方式时需要权衡 access_token 的隐私性或需要教导对方如何获取自己的 access_token。这或多或少地给工作流与协作过程带来了不便。
5. 检查 API 输出的内容是否可被 ProtoPie 解析
从 ProtoPie Studio 7.9 开始，在功能上增加了对自托管媒体的支持，由此使得 API 接口上取回的数据有了更丰富的展现途径，为原型创意的发挥提供了更广袤的空间。
自托管媒体功能从文件格式来说，支持图像及视频的常见格式（可参阅此处）；从 Studio 功能来说，支持以资源链接或表达式方式提供，而表达式的实质也是给出相应的资源连接。由此显而易见的，只有 API 接口返回的内容符合下列情形，才能在原型上进行展现：
- 文本
- 普通明文——直接在原型上进行展现
- json文本——使用 parseJson 及其它表达式功能解析后在原型上进行展现
- 图片
- 图片网址——使用 parseJson 及其它表达式功能解析出网址后使用自托管媒体功能进行展现
- Base64 图片数据——将图片数据放置到变量中再采用表达式的方式使用自托管媒体功能进行展现（仅企业版支持该功能）
- 视频
- 视频网址——使用 parseJson 及其它表达式功能解析出网址后使用自托管媒体功能进行展现
以下给出一些例子说明上述情形：
- 例1：百度地图开放平台的国内天气查询 API ()，调用后其返回情况如下图所示：
百度地图开放平台的国内天气查询 API 调用结果示例
需要获取天气情况，可以采用
parseJson(变量,”result.now.text”) 这样的表达式进行获取。- 例2：图片资源网站 IMGAPI 的真人/动漫/风景调用 API，选择 json 作为返回格式，调用后其返回情况如下图所示：
IMGAPI 的 真人/动漫/风景调用 API 调用结果示例
将表达式
parseJson(变量,”imageurl”) 填写为替换媒体（图片）的来源地址，即可原型展示时实现动态设置该图片。以上就是对于 Connect API 插件，在使用前需要区分是否适用时应该考虑的各项内容。
对于上述1~4中，使用 API 插件无法做到的所有情形（譬如访问协议不匹配、一次需要传输多个项等），在需要实现时，可以通过开发相应的定制化 Bridge App 进行解决，同时，采用 Bridge App 的方式还能实现更大范围的原型与定制软硬件之间的集成与联动。
如果在工作处理过程中发现了某些情形在上面的内容中没有提及，从而不好自行判断时，欢迎联系ProtoPie 客服团队进行询问了解。