Function은 Channel 또는 다른 앱이 앱 서버에 요청하는 typed RPC입니다. 요청의 method가 Function의 전체 이름이고 params가 입력입니다. 앱 고유 Function은 orders.get처럼 standalone으로 등록하고, 표준 Extension Function은 Extension 이름과 relative name으로 전체 이름을 만듭니다.
수신 요청은 다음 JSON-RPC-like envelope를 사용합니다.
method: discovery에 공개된 정확한 전체 Function 이름params: schema로 검증할 입력context: caller, Channel, language, auth/config처럼 호출 surface가 제공하는 문맥systemVersion: AppStore와 앱 서버 사이에서 적용되는 시스템 계약을 식별하는 값
공개 JSON field는 TypeScript와 Go 모두 camelCase를 사용합니다. context는 raw body 기반 x-signature 검증이 성공한 요청에서만 신뢰하세요.
성공은 result, 예상 가능한 실패는 구조화된 error를 반환합니다.
대표 code는 처리할 수 없는 입력 1, bad request 2, not found 3, unauthorized 4, method not found -32601, internal error -32603입니다. type은 programmatic handling에 쓸 수 있게 안정적으로 유지하고, error에 credential이나 고객 데이터를 넣지 마세요. 전체 envelope는 공통 protocol을 기준으로 합니다.
호출을 완료하려면 사용자의 선택이 더 필요한 경우 성공 결과로 NeedsUserInputResultSchema를 반환할 수 있습니다. 한 번의 결과에 필요한 질문을 모두 담고, 다음 호출은 같은 Function에 기존 continuationToken과 실제로 받은 답만 전달합니다.
continuationToken은 사용자에게 표시하지 않는 opaque 값입니다. 만료 시간을 두고 앱, Function, Channel, caller에 바인딩해 서명하세요. 재개 호출도 새 호출과 동일하게 입력 검증, 권한 검증, 실행 정책을 적용해야 합니다. token에 credential이나 원문 고객 데이터를 넣지 마세요.
Developer portal에는 Function root를 등록하고 AppStore는 system version이 붙은 route를 호출합니다.
SDK가 route, dispatch, schema validation, error envelope와 extension.core.function.getFunctions discovery를 처리합니다. Raw JSON-RPC router나 수동 discovery 응답을 만들지 마세요. TypeScript는 SignatureGuard와 rawBody: true, Go는 server.WithSignature로 정확한 request bytes의 HMAC-SHA256 signature를 검증합니다.
Route suffix의 v1과 request의 systemVersion은 같은 AppStore 시스템 계약을 전달합니다. 현재 TypeScript와 Go SDK는 URL의 :version이나 request의 systemVersion별로 handler 집합을 나누지 않으며, signature 검증 후 dispatch 기준은 정확한 method입니다. 따라서 /functions/v1은 개발자가 소유하는 API version namespace가 아닙니다.
앱이 소유한 standalone Function에 breaking change가 필요하면서 기존 caller와의 호환성을 유지하려면 기존 orders.get을 그대로 두고 새 계약을 orders.getV2처럼 별도 이름으로 등록하세요. Metadata와 caller는 준비가 끝난 뒤 새 이름을 명시적으로 참조하게 변경합니다. systemVersion: "v2"나 /functions/v2를 이 용도로 사용하지 마세요. 표준 Extension Function은 공식 Function 이름을 임의로 바꾸지 않고 AppStore와 SDK가 제공하는 새 시스템 계약을 따라야 합니다.
TypeScript 앱은 decorator API와 Zod schema를 사용합니다.
@Extension({ name: "command" })이 있는 provider에서 @Func("metadata.getCommands")를 등록하면 전체 이름은 extension.command.metadata.getCommands가 됩니다. Standalone Function provider에는 가짜 @Extension을 붙이지 마세요. 모든 decorated class를 NestJS module의 providers에 추가해야 discovery됩니다.
Go는 builder와 generic handler를 사용합니다.
appsdk.Register와 appsdk.MustRegister는 Go struct에서 schema를 만들고, 입력이 Validate() error를 구현하면 자동으로 호출합니다. 명시적인 계약에는 appsdk.InputSchema, appsdk.OutputSchema, proto helper를 사용하세요.
Native Function은 반대 방향으로 앱이 Channel 기능을 호출합니다. App token이나 channel token을 TokenManager에서 얻고 typed proxy/client를 우선 사용하세요. 지원 목록은 고정된 문서 표가 아니라 현재 SDK의 TypeScript NativeFunctionTypeMap과 Go native.Client export가 기준입니다.
다른 앱 또는 자신의 등록된 Function을 AppStore를 통해 호출할 때는 SDK의 app-function client를 사용합니다.
Access token이 있다고 business authorization이 생기는 것은 아닙니다. Target app, 설치 Channel, caller와 요청 대상의 관계를 handler에서 다시 검증하세요. 자세한 내용은 TypeScript Native Function 레퍼런스와 Go Native Function 레퍼런스를 확인하세요.
표준 Extension은 SDK schema와 Function 이름을 제공하는 전용 helper를 우선 사용합니다. Go에는 extension/config, extension/oauth, extension/calendar, extension/command, extension/widget, extension/customtab, extension/hook, extension/polling, extension/store, extension/messaging, extension/alftask, extension/wms 등이 있습니다. SDK helper가 없는 standalone Function만 generic registration으로 격리하세요.
다음으로 Command 가이드, WAM 가이드, Extension 전체 가이드, 프로덕션 준비 가이드를 확인하세요.
이 문서는 Channel App SDK와 함께 관리합니다. 최신 패키지와 전체 문서 순서는 SDK README를 먼저 확인하세요. 이 Document의 기준 원문은 GitHub 원문입니다.