常见交互
API 插件高级教程
深入研究演示 API 插件的更高级示例，包括 Ask ChatGPT 教程。
Jeff Clarke, UX Designer & ProtoPie Educator
October 16, 2023
在本系列的第一部分中 ，我们了解了 API 插件以及如何使用它的基础知识。如果您还没有阅读它，最好在继续阅读本文之前先检查一下。在第二部分中，我们将看一些更实际的例子。
示例 1：基于交互自定义请求
我们在第一篇文章中探讨的基本示例很简单。我们每次都向同一 URL 发送请求并使用响应。但是，您经常会发现每次都需要自定义请求 URL。在此示例中，我们将创建一个字典查找体验，您可以在其中键入任何单词并将其传递给 API 以检索其定义。
为此，我们将使用免费词典 API 。API 请求 URL 如下所示：
https://api.dictionaryapi.dev/api/v2/entries/en/<word>请注意 URL 末尾标记为 的部分。我们将这部分替换为我们要查找的实际单词。
<word>例如，要查找“chicken”一词的定义，我们将使用以下 URL：
https://api.dictionaryapi.dev/api/v2/entries/en/chicken要查找“little”一词的定义，我们将使用此URL：
https://api.dictionaryapi.dev/api/v2/entries/en/little本质上，每个单词都有自己唯一的URL。回想一下上一篇文章 ，在ProtoPie Connect API插件中，我们只能配置一个URL。在此示例中，我们将了解如何处理这种情况。
配置 API 插件
ProtoPie Connect API 插件允许您用 Pie 提供的请求 URL 覆盖请求 URL。这使我们能够在 Studio 中动态构建 URL，并将其作为 Pie 发送的消息的值提供以触发 API 请求。
在ProtoPie Connect中，我们将以与第一个示例中类似的方式配置插件，但有一个显着的区别：
- 这一次，将 URL 字段留空。相反，在“来自饼图的消息”字段下方，选中“覆盖”旁边的框。将下拉列表保留为默认 URL。
- 用您喜欢的任何消息填写来自饼图的消息和发送到饼图的消息字段。我分别使用和。
DICTIONARY_REQUESTDICTIONARY_RESPONSE - 单击激活。
配置API插件
注意：您将无法测试连接，因为插件当前不知道要请求的 URL。
创作你的”原型”
下载此示例的起始 Pie，并在 Studio 中打开它。
这个馅饼中有两个场景：“dictionary - home”和“dictionary - result”。我们将在“dictionary - result”场景中完成所有工作。
我们将在“字典 - 结果”场景中完成所有工作。
请注意，大部分工作已经完成，但请注意到目前为止尚未配置的两个 Send 响应：一个在“开始”触发器下，另一个在“返回”触发器下。这两者都是相同的，因此我们将配置一个并将其复制到另一个。
在“开始”触发器下配置“发送”响应，如下所示：
- 使用频道ProtoPie Studio。
- 使用您在插件的“消息到饼”字段中配置的消息。就我而言，我使用的消息是.
DICTIONARY_REQUEST
这是关键部分：您与此消息一起传递的值将是插件使用的 URL。
- 选中“一起发送值”旁边的框。
- 在显示的公式字段中，使用以下公式：
"<https://api.dictionaryapi.dev/api/v2/entries/en/>" + searchWord
在显示的公式字段中，使用指示的公式。
我们刚刚做了什么？
请求 URL 每次都相同，除了最后一部分，我们在其中附加了我们要查找的单词，该单词存储在变量中。通过在这样的公式中构建 URL，我们可以在每次发出请求时向插件提供一个动态生成的 URL。
searchWord在返回触发器下的 Pie 中，我们还有另一个未配置的发送响应。您可以按照与上面相同的方式配置该响应，也可以将刚刚做出的发送响应复制到下面的返回触发器中。然后，您可以根据需要删除剩余的未配置占位符。
专业提示：确保将复制的“发送”响应粘贴到“分配搜索词 =
输入.文本”响应下方。否则，您的 Pie 将使用前一个单词向 API 发出请求。此 Pie 已设置接收触发器以接收来自 API 的响应并使用它，因此您无需配置该部分。但是，如果您有兴趣，请查看该触发器中使用的多个文本响应，以使用 JSON 中多个键的值填充多个文本层。
触发器中使用的多个文本响应。
在ProtoPie Connect中运行Pie
与第 1 部分一样，我们需要在 ProtoPie Connect 中运行 Pie 以查看我们的实时数据。将馅饼拖入连接，预览它，然后亲自尝试一下！
注意：记得在运行之前保存你的原型！
在ProtoPie Connect中运行Pie。
处理错误
注意：在撰写本文时，ProtoPie Connect 2.6.1尚未发布，因此如果您正在尝试此操作并且您拥有的最新版本是2.6，则本节将不适用。坚持下去，因为 2.6.1 应该在 2023 年 9 月底发布。
如果您尝试过这种方法，您可能会遇到什么都没有返回馅饼的情况。如果您键入的单词不正确，或者搜索字典中不存在的单词，则可能会发生这种情况。API 被编程为处理此类事件，并返回错误状态代码。
这里有一个例子，我拼错了“bananas”这个词。单击以下网址。
请注意，您得到的响应与查找实际单词时的响应有何不同。如果您使用 Chrome 的开发者工具右键单击并检查相应网页，则会看到系统报告了错误。具体来说，它返回错误代码 404，这是“未找到”的标准互联网错误代码。
错误代码 404 - “未找到”的标准互联网错误代码
API 插件识别这种情况，并向 Pie 提供不同的 JSON。这就是结果返回空白的原因。Pie 期望以特定方式格式化 JSON，但发回的错误 JSON 与该格式不匹配。
{
"status": "Error",
"status-code": 404,
"response": {
...whatever is returned from the API...
}
}在我们的 Pie 中，我们可以查找密钥的存在，看看它的值是否为 如果是这样，我们可以采取替代操作并向用户显示适当的消息。
"status"“Error.”在工作室中，查找接收消息的触发器。
DICTIONARY_RESPONSE- 添加条件
- 按如下方式配置条件：
- 如果：
- 公式：
parseJson(defintionJson, "status")
- 公式：
- 等于
- 价值：
“Error”
- 价值：
- 如果：
添加条件
此原型中有一个名为“无结果部分”的图层组。默认情况下，它是隐藏的，但在这种情况下，我们将使其可见。
- 在刚刚创建的条件下添加不透明度响应。
- 将“无结果部分”图层组的不透明度设置为 100。
将“无结果部分”图层组的不透明度设置为 100。
将“无结果部分”图层组的不透明度设置为 100
- 保存您的作品，然后通过ProtoPie Connect再次预览。
注意：当同时使用ProtoPie Connect和Studio时，Connect将识别文件何时保存，并自动在Web视图中重新加载Pie。只需返回浏览器并再次与之交互即可。
现在，当您搜索 API 找不到的内容时，您将看到“找不到定义”消息。
“未找到定义”
示例 2：ChatGPT聊天
我相信这是你们都想看到的例子！是的，使用像ProtoPie中的ChatGPT这样的对话AI创建完全工作体验是100%可能的。
这绝对是如何使用 API 插件的高级示例，因此您需要转到文档 并熟悉 ChatGPT API 的工作原理。您还需要一个 API 密钥，以便在向 API 发出请求时对自己进行身份验证。不幸的是，这不是免费的，但对于这样的探索性用途来说，它非常便宜。转到开放 API 的定价页面 以开始使用。
配置 API 插件
像前面的所有示例一样，我们从设置 ProtoPie Connect API 插件开始。按如下方式配置插件：
- 方法：发布
- 我们以前从未接触过此配置。RESTful API 适用于 GET 或 POST 类型的请求。了解其中的区别并不重要 - 大多数 API 的文档会告诉您使用哪一个。一个好的经验法则是，如果您需要使用插件中的 Body 配置，您可能需要使用 POST。 否则，GET 可能会完成工作（看看我在那里做了什么？
- 网址：
https://api.openai.com/v1/chat/completions - 标题：
{
"Content-Type": "application/json",
"Authorization": "Bearer <YOUR API KEY>"
}- 这是我们尚未使用的另一个配置。标头允许您指定有关请求的信息。所有请求都有一个标头，但在前面的示例中，我们只是使用了后台的默认值。此配置使您有机会显式设置一些标头值。在本例中，我们已指定请求的正文将采用 JSON 格式，并指定了如何授权请求。
- 确保按照 OpenAI 提供的方式替换标有实际 API 密钥的部分。
<YOUR API KEY> - 来自派的消息：
ASK CHAT GPT- 选中覆盖旁边的框，这次从下拉列表中选择 Body — 我们将在 Pie 中制定请求的正文。
- 给派的消息：
CHAT GPT ANSWER - 点击激活
- 注意：如果单击“测试请求”，则会收到错误。目前，请求没有正文，因此 ChatGPT API 没有任何可处理的内容。
创作原型
下载下面的起始 Pie 并在 ProtoPie Studio 中打开它
再一次，我们有一个名为“发送询问聊天 GPT”的未完成的发送响应，在名为“点击让我们完成它”的触发器下。
Send.
设置发送响应
设置发送响应。
- 与往常一样，使用Protopie Studio Channel。
- 使用消息
ASK CHAT GPT - 与前面的示例一样，我们希望包含一个值。但是，这一次，我们将覆盖请求的正文，而不是 URL。
下面是对聊天 GPT API 的请求格式正确的正文参数示例：
{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
],
"temperature": 1,
"max_tokens": 256,
"top_p": 1,
"frequency_penalty": 0,
"presence_penalty": 0
}在我们的例子中，我们希望将键的值替换为用户在输入字段中键入的任何问题。从本质上讲，我们将为一些将被替换的文本制作一个带有令牌的模板。它可能看起来像这样：
"content"{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "Reply in no more than 3 sentences. <<USER_QUERY>>"
}
],
"temperature": 1,
"max_tokens": 256,
"top_p": 1,
"frequency_penalty": 0,
"presence_penalty": 0
}当我们发送请求时，我们会将该部分替换为用户提出的实际问题。此外，让我们指导 ChatGPT 我们希望如何回应。让我们按如下方式修改模板：
<<USER_QUERY>>{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "Reply in no more than 3 sentences. <<USER_QUERY>>"
}
],
"temperature": 1,
"max_tokens": 256,
"top_p": 1,
"frequency_penalty": 0,
"presence_penalty": 0
}这样，用户的问题将始终以“回复不超过 3 句话”开头，然后是实际问题。
现在，要将其创建为模板，我们将在 Studio 中创建一个包含上述内容的文本变量。
- 在 ProtoPie Studio 的左下角，单击“变量”选项卡以打开变量面板（如果尚未打开）。
- 创建一个变量。命名它 .
BODY_TEMPLATE - 确保将其设置为文本类型。在工作室界面的右上角，选择变量属性中的文本
- 在选择“文本类型”的正下方有一个空文本框。复制上面的模板代码段并将其粘贴到此文本字段中。这将设置变量的初始值。
复制上面的模板代码段并将其粘贴到文本字段中
该框不够大，无法显示整个模板正文，但不要担心。一切都在那里
- 现在返回到“发送”响应。
- 选中“一起发送值”旁边的框
- 在出现的公式框中，使用以下公式：
replace(BODY_TEMPLATE, "<<USER_QUERY>>",Input.text)
出现的公式框中，使用指示的公式
我们刚刚做了什么？
我们使用ProtoPie的函数（此处为docs ）获取存储在变量中的文本，查找确切的文本，并将其替换为输入字段中的任何内容。请记住，这不会修改变量。该函数的输出是一个新的文本位。我们只是获取该输出并将其直接作为消息的值传递。
replace()BODY_TEMPLATE<<USER_QUERY>>BODY_TEMPLATEreplace()与前面的示例一样，已为您创建了与 API 响应配合使用的接收触发器。如果您愿意，可以看看，但您会发现它与我们之前的示例非常相似。保存您的馅饼 — 我们在工作室中完成了！
将完成的 Pie 拖到 ProtoPie Connect 中并运行它。你应该有一个工作 ChatGPT 经验！
完成原型！
使用 API 插件将真实数据引入您的设计中
ProtoPie API 插件使您能够将真实的动态数据注入到您的设计中，将您的原型提升到一个新的真实感和功能水平。制作真实体现您愿景的交互式数据驱动原型。