이 시리즈의 첫 번째 부분에서는 API 플러그인과 이를 사용하는 기본 방법에 대해 배웠습니다. 아직 읽지 않으셨다면, 이 글을 계속 읽기 전에 먼저 확인해 보는 것이 좋습니다. 두 번째 부분에서는 좀 더 실용적인 예제를 살펴보겠습니다.
예제 1: 상호작용에 따라 요청 사용자 지정
첫 번째 글에서 살펴본 기본 예제는 간단했습니다. 우리는 매번 같은 URL로 요청을 보내고 응답을 사용했습니다. 하지만 실제로는 요청 URL을 매번 사용자 지정해야 하는 경우가 많습니다. 이 예제에서는 어떤 단어든 입력하면 해당 정의를 가져오기 위해 API에 전달하는 사전 조회 경험을 만들어 보겠습니다.
이 작업에는 Free Dictionary 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을 동적으로 만들고, API 요청을 트리거하기 위해 Pie가 보내는 메시지의 값으로 전달할 수 있습니다.
ProtoPie Connect에서 플러그인을 첫 번째 예제와 비슷한 방식으로 구성하되, 한 가지 중요한 차이가 있습니다:
이번에는 URL 필드를 비워 둡니다. 대신 Message From Pie 필드 아래에서 Override 옆의 체크박스를 선택하세요. 드롭다운은 기본값인 URL로 둡니다.
Message from Pie 및 Message to Pie 필드에 원하는 메시지를 입력합니다. 저는 각각
DICTIONARY_REQUEST와DICTIONARY_RESPONSE를 사용했습니다.Activate를 클릭합니다.
API 플러그인 구성하기.
참고: 플러그인은 아직 요청할 URL을 알지 못하므로 연결을 테스트할 수 없습니다.
API 프로토타이핑에 대한 독점 뉴스와 팁을 받아보세요!
Pie 작성하기
이 예제의 시작 Pie를 다운로드하여 Studio에서 여세요.
이 Pie에는 “dictionary - home”과 “dictionary - result.”의 두 개 Scene이 있습니다. 우리는 “dictionary - result” Scene에서 모든 작업을 진행할 것입니다.
우리는 “dictionary - result” Scene에서 모든 작업을 진행할 것입니다.
이미 많은 작업이 완료된 것을 볼 수 있지만, 아직 구성되지 않은 두 개의 Send 응답에 주목하세요. 하나는 Start 트리거 아래에 있고, 다른 하나는 Return 트리거 아래에 있습니다. 이 둘은 같으므로, 하나를 구성한 다음 다른 하나에 복사할 것입니다.
Start 트리거 아래의 Send 응답을 다음과 같이 구성합니다:
채널 ProtoPie Studio를 사용합니다.
플러그인에서 Message to Pie 필드에 설정한 메시지를 사용합니다. 제 경우에는
DICTIONARY_REQUEST였습니다.
핵심은 이 메시지와 함께 전달하는 값이 플러그인이 사용할 URL이라는 점입니다.
Send Value Together 옆의 체크박스를 선택합니다.
나타나는 수식 필드에 다음 수식을 사용합니다:
"<https://api.dictionaryapi.dev/api/v2/entries/en/>" + searchWord
나타나는 수식 필드에 표시된 수식을 사용합니다.
우리가 방금 한 일은?
요청 URL은 마지막 부분을 제외하면 매번 같습니다. 마지막 부분에는 조회하려는 단어를 붙이는데, 이 단어는 searchWord 변수에 저장되어 있습니다. 이처럼 수식으로 URL을 만들면, 요청할 때마다 동적으로 생성된 URL을 플러그인에 전달할 수 있습니다.
우리 Pie에는 아직 Return Trigger 아래에 구성되지 않은 Send 응답이 하나 더 있습니다. 위와 같은 방법으로 구성해도 되고, 방금 만든 Send 응답을 아래의 Return Trigger로 복사해도 됩니다. 원한다면 남아 있는 구성되지 않은 자리 표시자는 삭제할 수 있습니다.
전문가 팁:* 복사한 Send 응답을 “Assign searchWord = Input.text” 응답 아래에 붙여넣는 것을 잊지 마세요. 그렇지 않으면 Pie가 이전 단어로 API 요청을 보내게 됩니다.*
API의 응답을 받도록 이미 Receive trigger가 설정되어 있으므로, 그 부분은 구성할 필요가 없습니다. 하지만 관심이 있으시다면, 그 Trigger에서 여러 JSON 키의 값을 사용해 여러 Text 레이어를 채우는 데 사용되는 여러 Text 응답을 살펴보세요.
Trigger에서 사용되는 여러 Text 응답.
ProtoPie Connect에서 Pie 실행하기
1부와 마찬가지로, 실시간 데이터를 확인하려면 ProtoPie Connect에서 Pie를 실행해야 합니다. Pie를 Connect로 드래그하고 미리 보기를 실행한 뒤 직접 사용해 보세요!
참고: 실행하기 전에 Pie를 저장하는 것을 잊지 마세요!
ProtoPie Connect에서 Pie를 실행하는 중.
오류 처리하기
참고: 이 글을 작성하는 시점에는 ProtoPie Connect 2.6.1이 아직 출시되지 않았으므로, 이 내용을 따라 해 보려는 분이 최신 버전 2.6을 사용 중이라면 이 섹션은 해당되지 않습니다. 2.6.1은 2023년 9월 말까지 출시될 예정이니 조금만 기다려 주세요.
직접 시도해 보셨다면, 아무것도 Pie로 반환되지 않는 상황을 겪었을 수 있습니다. 단어를 잘못 입력했거나 사전에 존재하지 않는 단어를 검색할 때 이런 일이 발생할 수 있습니다. API는 이러한 상황을 처리하도록 설계되어 있으며, 오류 상태 코드를 반환합니다.
여기 “bananas”를 잘못 입력한 예가 있습니다. 다음 URL을 클릭하세요.
https://api.dictionaryapi.dev/api/v2/entries/en/bannas
실제 단어를 조회할 때와 응답이 어떻게 다른지 보세요. Chrome 개발자 도구로 페이지를 오른쪽 클릭해 검사하면 오류가 보고되는 것을 볼 수 있습니다. 구체적으로는 표준 인터넷 오류 코드인 404,를 반환하는데, 이는 “찾을 수 없음.”을 의미합니다.
오류 코드 404 - “찾을 수 없음.”을 의미하는 표준 인터넷 오류 코드.
API 플러그인은 이 상황을 인식하고 Pie에 다른 JSON을 반환합니다. 그래서 결과가 비어 보이는 것입니다. Pie는 특정 형식의 JSON을 기대했지만, 반환된 오류 JSON은 그 형식과 일치하지 않습니다.
플러그인에서 반환된 오류 JSON은 다음과 같습니다:
우리 Pie에서는 "status" 키의 존재를 확인하고 그 값이 “Error.”인지 볼 수 있습니다. 그렇다면 다른 동작을 수행하여 사용자에게 적절한 메시지를 표시할 수 있습니다.
Studio에서 DICTIONARY_RESPONSE 메시지를 받는 Trigger를 찾으세요.
Condition을 추가합니다
조건을 다음과 같이 구성합니다:
IF:
Formula:
parseJson(defintionJson, "status")EQUALS
Value:
“Error”
조건을 추가합니다.
이 Pie에는 “no results section”이라는 레이어 그룹이 있습니다. 기본적으로는 숨겨져 있지만, 이 상황에서는 보이도록 설정합니다.
방금 만든 Condition 아래에 Opacity 응답을 추가합니다.
“no result section” 레이어 그룹의 Opacity를 100으로 설정합니다.
“no result section” 레이어 그룹의 Opacity를 100으로 설정합니다.
작업을 저장한 다음 ProtoPie Connect를 통해 다시 미리 보기를 실행합니다.
참고: ProtoPie Connect와 Studio를 동시에 사용할 때, 파일이 저장되면 Connect가 이를 인식하고 웹 뷰의 Pie를 자동으로 다시 불러옵니다. 브라우저로 돌아가 다시 상호작용하면 됩니다.
이제 API가 찾을 수 없는 것을 검색하면 “정의를 찾을 수 없습니다.” 메시지가 표시됩니다.
“정의를 찾을 수 없습니다.” 메시지.
예제 2: ChatGPT
이 예제가 여러분이 모두 보고 싶어 했던 예제라고 확신합니다! 네, ProtoPie에서 ChatGPT 같은 대화형 AI로 완전히 작동하는 경험을 만드는 것은 100% 가능합니다.
이것은 API 플러그인을 사용할 수 있는 방법에 대한 확실히 고급 예제이므로, 문서를 살펴보고 ChatGPT API가 어떻게 작동하는지 익혀 두는 것이 좋습니다. 또한 API에 요청할 때 본인을 인증하기 위한 API 키도 필요합니다. 안타깝게도 이것은 무료는 아니지만, 이런 탐색용 용도로는 매우 저렴합니다. 시작하려면 OpenAI의 가격 페이지로 가세요.
API 플러그인 구성하기
이전 예제들과 마찬가지로 ProtoPie Connect API 플러그인을 설정하는 것부터 시작합니다. 플러그인을 다음과 같이 구성하세요:
Method: POST
이전에는 다루지 않았던 설정입니다. RESTful API는 GET 또는 POST 유형의 요청과 함께 작동합니다. 둘의 차이를 정확히 이해하지 못해도 괜찮습니다. 대부분의 API 문서가 어떤 것을 사용해야 하는지 알려 줄 것입니다. 일반적인 규칙은 플러그인에서 Body 구성을 사용해야 한다면 POST를 사용해야 할 가능성이 높다는 것입니다. 그렇지 않다면 GET이 아마도 일을 잘 처리해 줄 것입니다(방금 제가 한 말, 보이시나요?).
URL:
https://api.openai.com/v1/chat/completionsHeader:
여기서도 아직 사용하지 않은 다른 설정이 있습니다. Header를 사용하면 요청에 대한 정보를 지정할 수 있습니다. 모든 요청에는 header가 있지만, 이전 예제들에서는 내부적으로 기본값만 사용했습니다. 이 설정을 통해 일부 header 값을 명시적으로 지정할 수 있습니다. 이 경우 요청 본문이 JSON 형식이 되도록 지정하고, 요청을 승인하는 방법도 지정했습니다.
<YOUR API KEY>라고 표시된 부분을 OpenAI가 제공한 실제 API 키로 바꾸세요.Message from Pie:
ASK CHAT GPTOverride 옆의 체크박스를 선택하고, 이번에는 드롭다운에서 Body를 선택하세요. 요청의 본문을 Pie에서 구성할 것입니다.
Message to Pie:
CHAT GPT ANSWERActivate를 클릭합니다
참고: Test Request를 클릭하면 오류가 발생합니다. 현재 요청에는 body가 없으므로 ChatGPT API가 사용할 내용이 없습니다.
API 플러그인 구성하기.
Pie 작성하기
아래에서 시작 Pie를 다운로드하여 ProtoPie Studio에서 여세요.
이번에도 Tap Send.라는 Trigger 아래에 Send ASK CHAT GPT라는 완료되지 않은 Send 응답이 있습니다. 마무리해 보겠습니다.
Send 응답 설정하기.
언제나 그렇듯 ProtoPie Studio 채널을 사용합니다.
ASK CHAT GPT메시지를 사용합니다이전 예제처럼 값도 포함하고 싶습니다. 다만 이번에는 URL이 아니라 요청의 body를 덮어쓸 것입니다.
Chat GPT API에 요청할 때 올바르게 형식이 지정된 body 매개변수의 예는 다음과 같습니다:
우리의 경우, "content" 키의 값을 사용자가 입력 필드에 입력한 질문으로 바꾸고 싶습니다. 즉, 교체될 텍스트 일부를 위한 토큰이 들어 있는 템플릿을 만드는 것입니다. 다음과 같이 보일 수 있습니다:
요청을 보낼 때 <<USER_QUERY>> 부분을 사용자가 실제로 질문한 내용으로 바꿀 것입니다. 또한 ChatGPT가 응답을 어떤 방식으로 작성하길 원하는지도 알려 주겠습니다. 템플릿을 다음과 같이 수정해 보겠습니다:
이렇게 하면 사용자의 질문은 항상 “최대 3문장 이내로 답하세요,”로 시작하고 그 뒤에 실제 질문이 이어집니다.
이제 이것을 템플릿으로 만들기 위해 Studio에서 위의 내용을 포함하는 텍스트 변수를 만들겠습니다.
ProtoPie Studio 왼쪽 아래 모서리에서 Variables 탭을 클릭해 변수 패널을 엽니다. 이미 열려 있다면 그대로 두세요.
변수를 하나 만듭니다. 이름을
BODY_TEMPLATE로 지정하세요.텍스트 유형으로 설정되어 있는지 확인합니다. Studio UI 오른쪽 위에서 변수 속성의 Text를 선택하세요
Text 유형을 선택한 바로 아래에 빈 텍스트 상자가 있습니다. 위의 템플릿 스니펫을 복사하여 이 텍스트 필드에 붙여넣으세요. 이렇게 하면 변수의 초기값이 설정됩니다.
위의 템플릿 스니펫을 복사하여 텍스트 필드에 붙여넣으세요.
상자가 전체 템플릿 본문을 보여 주기에는 충분히 크지 않지만, 걱정하지 마세요. 다 들어 있습니다.
이제 Send 응답으로 돌아갑니다.
Send Value Together 옆의 체크박스를 선택합니다
나타나는 formula 상자에 다음 수식을 사용합니다:
```replace(BODY_TEMPLATE, "<<USER_QUERY>>",
Input.text)`
나타나는 formula 상자에 표시된 수식을 사용합니다.
우리가 방금 한 일은?
ProtoPie의 replace() 함수(여기 문서)를 사용하여 BODY_TEMPLATE 변수에 저장된 텍스트를 가져오고, 정확히 <<USER_QUERY>>라는 텍스트를 찾아 입력 필드에 있는 내용으로 바꿨습니다. 이때 BODY_TEMPLATE 변수 자체가 수정되는 것은 아닙니다. replace() 함수의 출력은 새로운 텍스트입니다. 우리는 그 출력을 그대로 메시지 값으로 전달하고 있을 뿐입니다.
이전 예제와 마찬가지로 API 응답과 함께 작동하는 Receive Trigger는 이미 만들어져 있습니다. 원하시면 살펴보셔도 되지만, 이전 예제들과 매우 비슷하다는 것을 알 수 있을 것입니다. Pie를 저장하세요. Studio에서 할 일은 끝났습니다!
완성된 Pie를 ProtoPie Connect로 드래그해 실행하세요. ChatGPT가 작동하는 경험을 확인할 수 있을 것입니다!
왜 과학자들은 원자를 믿지 않을까요? 왜냐하면 원자들은 모든 것을 만들어 내기 때문입니다!
완성된 Pie
API 플러그인으로 디자인에 실제 데이터를 가져오세요
ProtoPie API 플러그인을 사용하면 실제의 동적인 데이터를 디자인에 주입하여 프로토타입의 사실감과 기능을 한 단계 끌어올릴 수 있습니다. 여러분의 비전을 진정성 있게 구현하는 인터랙티브하고 데이터 기반인 프로토타입을 만들어 보세요.
