Weegloo Docs - Script

옷가게 쇼핑몰을 운영한다고 생각해 보세요. 상품을 올릴 때마다 매력적인 상세설명을 일일이 쓰는 일은 번거롭습니다. 그래서 상품명과 키워드만 넣으면 AI가 상세설명을 대신 써 주게 하고 싶습니다. 그런데 그 AI 글쓰기 서비스를 부르려면 비밀 열쇠(access token, 바깥 서비스가 "요금을 낸 사용자가 맞는지" 확인하는 열쇠)가 있어야 합니다. 이 열쇠를 손님이 보는 웹사이트(브라우저)에 넣어 두면 누구나 꺼내 볼 수 있어 새어 나갑니다. 새어 나간 열쇠로 남이 이 서비스를 마음대로 써서 요금을 물릴 수도 있습니다.

그래서 열쇠를 손님 눈에 닿지 않는 곳에 감춰 둔 채, 웹사이트 대신 AI를 불러 주고 그 결과를 상품에 채워 줄 무언가가 필요합니다. Script가 그것입니다. Script는 "이 열쇠로 AI를 부르고, 받은 문구를 이 상품의 상세설명에 채워라"처럼 할 일을 순서대로 적어 둔 것입니다. 코드가 아니라 정해진 양식(JSON, 항목과 값을 중괄호로 적는 데이터 표기 방식)으로 적습니다. 웹사이트는 이 Script를 인터넷으로 부르기만 하면 되고, 열쇠는 Script 안에 숨겨져 손님에게는 보이지 않습니다.

미리 적어 둔 조리법을 주방에 걸어 두는 것에 비유할 수 있습니다. 손님이 그 메뉴를 주문하면(웹사이트가 Script를 부르면), 주방(WEEGLOO)이 조리법에 적힌 순서대로 만들어 완성한 요리를 내어 줍니다. 주인은 조리법만 적어 걸어 두었을 뿐, 주문이 들어올 때마다 직접 요리하지는 않습니다. 이 페이지에서는 Script가 무엇이고 어떻게 생겼는지, 부르면 무엇을 돌려주는지 살펴본 뒤, 옷가게의 "상품 설명 채우기" Script를 예로 그 모양을 확인합니다. 마지막에는 이 Script를 상품이 등록될 때 저절로 실행되게 잇는 법도 봅니다.

Script가 대신 해 주는 일

상품 설명 하나를 채우는 일에도, 뒤에서 해야 할 일은 여러 가지입니다. 부르는 쪽에 권한이 있는지 확인하고, 보낸 값이 올바른지 검사하고, 감춰 둔 열쇠로 바깥 AI 서비스를 부르고, 받은 결과를 원하는 자리(상품의 상세설명)에 넣고, 응답을 돌려줍니다. 예전에는 이런 일을 하는 중간 프로그램을 직접 만들어 서버에 올리고 관리해야 했습니다. Script는 이 일들을 코드 없이 한곳에 적어 두어 대신하게 하는 것이 목표입니다.

하나의 Script는 하나의 호출 창구입니다. 웹사이트가 인터넷으로 부를 수 있는 창구 하나가 Script 하나입니다. 부를 때 쓰는 방식(method)으로 어떤 Script를 실행할지 맞춥니다.
할 일은 위에서 아래로 늘어놓습니다. Script 안에는 실행할 동작을 순서대로 적습니다. 위에서부터 차례로 실행되고, 앞 동작의 결과를 다음 동작이 이어받습니다.
정해진 동작을 골라 조합합니다. 아무 코드나 넣는 것이 아니라, 미리 마련된 동작(자원 만들기·읽기·수정·삭제, 바깥 서비스 호출, 값 담아 두기, 조건 검사, 반복 등)을 골라 늘어놓습니다.

무엇을 할지 적어 두는 정의

Script 하나는 네 가지를 정해 둔 "정의"로 이루어집니다.

부르는 방식(method): 이 Script를 부를 때 쓰는 방식입니다. Get·Post·Put·Patch·Delete 중 하나이고, 부를 때 이 값으로 어떤 Script인지 맞춥니다.
실행 위치(executionMode): 부른 자리에서 즉시 실행할지(Sync), 뒤에서 실행할지(Async)입니다. 아래 즉시 실행과 백그라운드 실행에서 다룹니다.
할 일(statements): 위에서 아래로 실행할 동작의 목록입니다. 적어도 하나는 있어야 합니다.
입력 검사(payloadSchema, 선택): 부를 때 함께 보내는 입력을 실행 전에 확인할 형식입니다. 정해 두면 형식에 맞지 않는 입력은 실행하지 않고 되돌립니다.

옷가게의 "상품 설명 채우기" Script를 예로 보겠습니다. 이 Script가 다루는 것은 상품명과 키워드가 담긴 상품 하나입니다. 웹사이트에서 넘겨주는 입력(뒤에서 볼 자동 실행 때는 등록된 상품이 그대로 전달됩니다)은 이런 모양입니다.

{
  "sys": { "id": "3trmXRMKq7bd0Prbef1... (상품 번호)" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" },
    "keywords":    { "ko-KR": "보온, 가벼움, 캠핑" }
  }
}

이 상품을 받아, 바깥 AI로 상세설명을 만들고, 그 상품의 상세설명(body)을 채우는 Script의 정의입니다.

{
  "method": "Post",
  "executionMode": "Async",
  "statements": [
    { "type": "Http", "method": "POST",
      "url": "https://api.ai-writer.example.com/v1/generate",
      "headers": [
        { "key": "Authorization", "value": "Bearer <비밀 access token>", "secret": true }
      ],
      "body": {
        "product":  "{ /payload/fields/productName/ko-KR }",
        "keywords": "{ /payload/fields/keywords/ko-KR }"
      },
      "name": "gen" },
 
    { "type": "ResourcePatch", "resource": "Content",
      "target": { "sys": { "id": "{ /payload/sys/id }" } },
      "fields": { "body": { "ko-KR": "{ /gen/body/text }" } },
      "publish": true },
 
    { "type": "Return", "value": { "id": "{ /payload/sys/id }" }, "statusCode": 200 }
  ]
}

첫 동작(Http)이 감춰 둔 열쇠로 바깥 AI 서비스를 부릅니다. 열쇠를 담은 헤더에 secret: true를 붙이면, 그 값은 손님에게 보이지 않고 부르기 직전에만 풀립니다. 받은 결과는 gen이라는 이름에 담아 둡니다.
둘째 동작(ResourcePatch)이 앞에서 받은 문구({ /gen/body/text })로 그 상품의 상세설명(body)만 채웁니다. 상품의 나머지 값은 건드리지 않습니다.
값을 다음 단계로 흘려보내는 자리표시자 { /… }를 씁니다. { /payload/fields/productName/ko-KR }는 넘겨받은 상품의 이름을, { /payload/sys/id }는 그 상품의 번호를, { /gen/body/text }는 AI가 돌려준 문구를 가리킵니다.
마지막 동작(Return)이 설명을 채운 상품의 번호를 돌려줍니다.
Content의 값을 { "ko-KR": … }처럼 언어별로 적는 이유, statements에 넣을 수 있는 동작의 전체 종류, 자리표시자와 조건·계산 문법은 값 표현식과 Statement 카탈로그에서 다룹니다.

부르면 무엇을 돌려주나

Script는 맨 끝에서 Return 동작의 값을 부른 쪽에 돌려줍니다. 돌려주는 응답에는 다음이 담깁니다.

requestId: 이번 실행을 가리키는 식별 번호입니다.
durationMs: 실행에 걸린 시간(밀리초)입니다.
statusCode: 도달한 Return의 상태 코드입니다(따로 정하지 않으면 200).
return 또는 error: Return이 돌려준 값입니다. 보통은 return에 담기고, 그 값을 오류로 표시해 두면 error에 담깁니다. 둘이 함께 나오지는 않습니다.

다만 "상품 설명 채우기"는 바깥 AI를 부르므로 백그라운드로 실행됩니다(아래 즉시 실행과 백그라운드 실행 참조). 그래서 부르면 우선 "접수했다"는 뜻으로 202와 requestId만 즉시 돌아오고, 위 응답은 잠시 뒤 그 requestId로 다시 물어(폴링해) 받습니다. 다 끝난 응답은 이런 모양입니다.

{
  "requestId": "3trmXRMZ8kqLb2Prdf1eYc0axWnKv",
  "durationMs": 1840,
  "statusCode": 200,
  "return": { "id": "3trmXRMKq7bd0Prbef1... (상품 번호)" }
}

웹사이트는 이 return의 id로 방금 설명이 채워진 상품을 짚어, 새 상세설명을 손님에게 보여 줄 수 있습니다.

Return에 닿지 않고 Script가 끝나면 return도 error도 없이 statusCode만 200으로 돌아옵니다. Return으로 응답 본문과 상태 코드를 정하는 자세한 규칙은 Statement 카탈로그의 Return에서 다룹니다.

즉시 실행과 백그라운드 실행

Script는 두 가지 방식으로 실행할 수 있고, 정의의 executionMode로 정합니다.

즉시 실행(Sync): 부른 그 자리에서 바로 실행하고, 완성된 응답을 곧바로 돌려줍니다. 바깥 호출 없이 금방 끝나는 일에 알맞습니다.
백그라운드 실행(Async): 뒤에서 실행합니다. 부르면 우선 "접수했다"는 뜻으로 202와 requestId만 즉시 돌려주고, 실제 결과는 나중에 그 requestId로 다시 물어(폴링해) 가져옵니다.

한 가지 규칙이 있습니다. 바깥 서비스를 부르는 동작이나 파일을 받아 Media로 들여놓는 동작이 하나라도 들어 있으면, 그 Script는 반드시 백그라운드 실행이어야 합니다. "상품 설명 채우기"도 바깥 AI를 부르므로 백그라운드 실행입니다. 즉시 실행으로 저장하려 하면 저장할 때 되돌려집니다. 바깥 응답이 늦어져도 부른 쪽을 붙잡아 두지 않기 위해서입니다.

실행에 쓸 수 있는 시간에도 예산이 있습니다. 즉시 실행은 기본 10초, 백그라운드 실행은 기본 60초입니다. 폴링하는 방법과 어떤 동작이 백그라운드 실행을 부르는지 같은 자세한 규칙은 실행 시맨틱, 제약, 보안에서 다룹니다.

Script는 누가 만드나

복잡한 동작을 사람이 손으로 하나하나 적기보다, Script는 AI 에이전트나 프로그램이 만들도록 설계됐습니다. AI 에이전트에게 "상품 설명을 채워 주는 창구를 만들어 줘"라고 말로 부탁하면, 에이전트가 위에서 본 것 같은 정의를 대신 만들어 줍니다. 말 한마디로 웹사이트 뒤에서 일할 창구 하나가 생기는 셈입니다.

AI 에이전트로 Script를 만드는 자세한 흐름은 말 한마디로 백엔드 만들기에서 다룹니다.

만들어진 Script는 관리 화면(콘텐츠 스튜디오)에서 사람이 보고 관리합니다. 이름과 정의를 확인하고, 필요하면 고치거나 지웁니다. 실제로 Script를 부르는 쪽은 손님이 보는 웹사이트나 앱(프런트엔드)입니다. 제품에 가입한 회원(ServiceUser) 신원으로는 Script를 실행만 할 수 있고, 만들거나 고치지는 못합니다.

Webhook과 어떻게 다른가

Script와 Webhook은 둘 다 바깥과 잇는 장치이지만, 부르는 방향이 반대입니다.

Webhook은 정해 둔 변화가 생기면(상품이 등록되는 것처럼) 저절로 반응합니다. 사람이 부르지 않아도 사건이 일어나면 저절로 움직입니다. 다만 부른 쪽에 결과를 돌려주지는 않습니다.
Script는 웹사이트가 필요할 때 직접 부르는 창구입니다. 불러야 실행되고, 그 실행의 결과를 즉시, 또는 백그라운드 실행이면 폴링으로 돌려받습니다.

"주인이 '설명 채우기'를 누르면 AI를 불러 상세설명을 받아 채운다"는 부르는 쪽이 결과를 기다리는 일이므로 Script가, "상품이 등록되면 자동으로 무언가가 일어난다"는 사건에 반응하는 일이므로 Webhook이 알맞습니다. 그리고 이 둘은 함께 쓸 수 있습니다. 바로 다음에서 봅니다.

등록만 하면 설명이 저절로 채워지게

지금까지는 주인이 "설명 채우기" 버튼을 눌러 Script를 직접 불렀습니다. 한 걸음 더 나아가, 버튼을 누르지 않아도 상품을 등록하는 순간 Script가 저절로 실행되게 할 수 있습니다. Webhook이 그 사건을 잡아 우리 Script를 대신 불러 주기 때문입니다.

흐름은 이렇습니다.

주인이 상품을 등록합니다. 이때 상품명과 키워드만 채우고, 상세설명은 비워 둡니다.
상품이 새로 등록되는 사건을 Webhook이 알아챕니다.
Webhook이 방금 등록된 상품을 그대로 우리 "상품 설명 채우기" Script에 넘겨 실행합니다.
Script가 바깥 AI로 상세설명을 만들어 그 상품의 상세설명(body)을 채웁니다.
잠시 뒤 상품 상세설명이 저절로 채워져 있습니다.

여기서 Script는 앞과 똑같은 것을 씁니다. 달라지는 것은 부르는 계기뿐입니다. 버튼 대신 "상품이 등록됐다"는 사건이 부르는 것입니다. 등록된 상품이 그대로 Script의 입력이 되므로, Script는 { /payload/sys/id }로 그 상품을 집어 상세설명을 채웁니다.

Webhook 쪽에서 정할 것은 세 가지입니다. 어떤 사건에 반응할지(상품이 새로 등록될 때), 어떤 상품에만 반응할지(상품 종류로 한정), 그리고 무엇을 할지(바깥 주소로 알리는 대신 우리 Script를 부르기)입니다.

Script가 채운 상세설명이 다시 "상품이 바뀌었다"는 사건을 일으켜 끝없이 반복되지 않을까 걱정할 수 있습니다. 그렇지 않습니다. Script의 쓰기는 따로 켜지 않는 한 새 사건을 일으키지 않고, 플랫폼도 끝없는 반복을 막습니다.

이렇게 잇는 자세한 설정은 Webhook에서 다룹니다.

Script가 특히 유용한 경우

바깥에 "이런 일이 생겼다"고 알리기만 하면 되는 일이라면 Webhook 하나로 충분합니다. 하지만 바깥 서비스를 부른 뒤 그 결과를 보고 이어서 판단하고 처리해야 한다면, 그 흐름 전체를 한곳에 묶는 Script가 필요합니다.

유료로 AI 이미지를 만들어 주는 기능을 예로 들어 보겠습니다. 손님이 이미지 생성을 요청하면 다음 일이 순서대로 일어나야 합니다.

손님의 크레딧이 충분한지 확인합니다. 모자라면 여기서 멈추고 "크레딧이 부족합니다"라고 알려 줍니다.
충분하면 비용만큼 크레딧을 먼저 차감합니다.
바깥 AI 서비스를 불러 이미지를 만듭니다.
만들어진 이미지를 Content로 저장합니다.
3번이나 4번에서 문제가 생기면, 방금 차감한 크레딧을 다시 되돌려 줍니다.

Webhook은 "요청이 들어왔다"고 바깥에 알릴 수는 있어도, 이렇게 결과를 보고 크레딧을 차감하거나 실패를 되돌리지는 못합니다. 여러 단계를 조건에 따라 잇고 실패하면 앞 단계를 되돌리는 일은 Script가 맡습니다. Script가 특히 제 몫을 하는 경우는 다음과 같습니다.

결과를 보고 이어서 처리해야 할 때: 바깥 서비스가 돌려준 응답에 따라 저장할지, 차감할지, 되돌릴지를 그 자리에서 판단합니다.
동시에 들어와도 어긋나면 안 될 때: 같은 손님이 짧은 사이에 두 번 요청해도 크레딧이 두 번 차감되면 안 됩니다. Script는 값을 읽은 뒤 저장하기 직전에 "그새 다른 요청이 이 값을 바꾸지 않았는지"를 버전으로 확인해, 어긋났으면 멈춥니다.
부르는 쪽에 없는 권한이 필요할 때: 손님은 크레딧 잔액을 스스로 직접 고칠 권한이 없습니다. 그런데도 차감이 안전하게 일어나는 것은, Script가 그것을 만든 사람의 권한을 위임받아 실행되기 때문입니다. 부르는 쪽에는 Script를 실행할 권한만 주면 됩니다. 이 위임은 아래 실행하고 관리할 권한에서 자세히 다룹니다.

이 예시를 실제 Script 정의로 어떻게 적는지는 쿡북의 크레딧 확인·차감·되돌리기 예시에서 다룹니다.

실행하고 관리할 권한

Script를 실행하거나 관리하려면 역할(SpaceRole)에 그에 맞는 권한이 있어야 합니다.

실행: Script를 부르려면 역할에 Script 실행 권한(Execute)이 있어야 합니다. 없으면 실행이 막힙니다.
관리: Script를 만들고, 고치고, 지우려면 각각 생성·수정·삭제 권한이 필요합니다.

Script를 실행할 때 확인하는 것은 부르는 쪽에 실행 권한(Execute)이 있는가, 이 하나뿐입니다. Script 안에 늘어놓은 개별 동작은 실행하는 그 순간에 따로 권한을 확인하지 않습니다. 실행이 허락된 프로그램을 부를 때, 그 프로그램을 실행할 권한만 보고 그 안에서 하는 일 하나하나까지 매번 허락을 받지는 않는 것과 같습니다.

그 대신 개별 동작의 권한은 실행할 때가 아니라 Script를 저장할 때 미리 확인합니다. 만든 사람이 그 Script 안 동작이 다루는 Content·Media 작업 권한을 실제로 갖고 있어야 저장됩니다. 예를 들어 "상품 설명 채우기" Script는 상품 Content의 상세설명을 고치므로, 만든 사람에게 상품을 고칠 권한이 없으면 저장이 되돌려집니다. 권한 없는 동작이 담긴 Script는 애초에 저장되지 않는 것입니다.

이렇게 보면 Script 실행은 그것을 만든 사람의 권한을 위임받아 대신 수행하는 것과 같습니다. 부르는 쪽이 스스로는 갖지 못한 작업이라도, 만든 사람이 할 수 있는 작업이면 Script를 통해 그대로 일어납니다. 그러므로 Script를 만들 때는 그 안에 어떤 동작을 담는지 신중히 정해야 합니다. 만든 사람의 권한이 곧 그 Script가 할 수 있는 일의 범위가 됩니다.

역할에 권한을 담는 방법은 역할과 권한에서 다룹니다.

알아 둘 것

발행이 없습니다. Script는 발행해서 방문자에게 전달되는 종류의 자원이 아니라, 관리 화면에서 만들어 두고 웹사이트가 불러 쓰는 창구입니다. 그래서 Content·Media와 달리 발행·발행취소 상태가 없고, 만들면 바로 쓸 수 있습니다. 고칠 때마다 버전만 하나씩 올라가고, 지울 때도 발행취소 같은 사전 단계 없이 바로 지워집니다.
개수에 한도가 있습니다. Script는 과금 대상이라 Organization 하나가 가질 수 있는 개수가 요금제별로 정해져 있습니다(Free 3개, Basic 10개, Pro 50개, Enterprise 무제한). 한도에 다다르면 새 Script를 만들 수 없고, 안 쓰는 Script를 지우면 한 자리가 다시 빕니다.

콘텐츠 스튜디오에서 관리하기

만들어진 Script는 콘텐츠 스튜디오의 Script 화면에서 보고 관리합니다. 왼쪽 메뉴에서 Script를 누르면 지금까지 만든 Script가 목록으로 나옵니다. 각 줄에 이름, 부르는 방식(HTTP 메서드), Script를 가리키는 Script ID, 실행 위치(실행 모드), 마지막으로 고친 날짜가 보입니다.

Script 목록 화면. "상품 설명 채우기" Script가 HTTP 메서드 POST, 실행 모드 Async로 한 줄 보이는 상태

정의는 보통 AI 에이전트가 대신 만들어 주지만, 이 화면에서 직접 만들 수도 있습니다. 새 Script는 목록 오른쪽 위의 생성 버튼으로 만듭니다.

목록 오른쪽 위의 생성 버튼을 누르세요.
이름 칸에 상품 설명 채우기를 입력하세요.
HTTP 메서드를 이 Script를 부를 방식(여기서는 POST)으로 고르세요.
실행 모드를 Async(백그라운드 실행)로 고르세요. 이 Script는 바깥 AI를 부르므로 반드시 백그라운드 실행이어야 합니다.
Statement 칸에 할 일을 적은 정의를 넣으세요. 위 "상품 설명 채우기" 예시의 정의를 그대로 넣으면 됩니다.

새 Script 생성 화면. 이름 "상품 설명 채우기", HTTP 메서드 POST, 실행 모드 Async, Statement 칸에 정의를 넣은 상태

부를 때 함께 보낼 입력을 실행 전에 검사하고 싶으면, Payload Schema의 Payload 검증을 켜고 검사할 형식을 적어 둡니다. 다 채웠으면 오른쪽 위의 저장 버튼을 누르세요.

목록에서 Script 하나를 누르면 상세 화면이 열립니다. 여기서 이름과 정의를 확인하고, 이 Script를 부를 주소(호출 URL)도 볼 수 있습니다. 정의를 고친 뒤 저장하면 버전이 하나 올라가고, 더는 쓰지 않는 Script는 삭제로 지웁니다.

상품 설명 채우기 Script 상세 화면. 이름·HTTP 메서드·실행 모드·ID·호출 URL과 Statement 정의가 보이는 상태

다음으로 할 일

Script 개요: Script를 이루는 정의의 최상위 구조와 실행 규칙, 문법 문서 묶음을 다룹니다.
Statement 카탈로그: statements에 넣을 수 있는 동작(자원 만들기·읽기·수정·삭제, 바깥 서비스 호출, 조건·반복 등)의 종류와 필드를 다룹니다.
Webhook: 상품이 등록되면 Script가 저절로 실행되게 잇는 것처럼, 정해 둔 변화가 생기면 자동으로 반응하게 하는 방법을 다룹니다.