외부 함수 실행¶
POST /api/v1/outer_function/execute
개요¶
중앙 Func 서비스에서 OpenAPI를 통해 호출이 허용된 함수를 실행합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용하며 routine.defaultAccess 권한이 필요합니다. 먼저 함수 목록에서 현재 허용된 content[].id를 획득하고, description/definition/kwargsJSON을 읽어 실제 비즈니스 효과를 확인한 뒤 funcBody.kwargs의 실제 값을 구성합니다. 예시 example__openapi.test는 해당 함수가 실제로 현재 카탈로그 배포에 존재하는 경우에만 적용되며, 다른 배포에서는 반드시 실제 ID와 해당 파라미터로 교체해야 합니다. 임의의 코드를 업로드하는 진입점이 아닙니다.
서버는 중앙 Func에 category=openapi/id와 일치하는 함수가 존재하는지 검증하며, 허용 결과는 funcId 기준으로 캐시됩니다(기본 3600초, 사이트에서 재정의 가능). 카탈로그에서 제거하더라도 기존 캐시가 즉시 무효화된다고 보장하지 않습니다. 실행 전 workspace_uuid와 workspace_token이 kwargs에 자동으로 기록되어 클라이언트의 동일 이름 값을 덮어씁니다. 다른 인터페이스에서 보고 Token을 획득하거나 수동으로 제출할 필요가 없으며, 이를 통해 워크스페이스를 전환할 수 없습니다. 여기서 주입되는 것은 워크스페이스 보고 Token이며 DF-API-KEY가 아닙니다. 비즈니스 필수 파라미터와 기본값은 여전히 해당 함수 정의를 따릅니다.
함수는 데이터를 쓰거나 알림을 트리거하는 등 외부 작업을 수행할 수 있으므로, 실행 전에 대상 함수의 부작용과 멱등성을 먼저 확인해야 하며 이 진입점을 읽기 전용 상태 확인 용도로 사용해서는 안 됩니다. 인터페이스는 타임아웃 시 미실행을 보장하지 않습니다. 실패/타임아웃 후에는 먼저 함수의 비즈니스 결과로 확인한 뒤 재시도 여부를 결정하십시오. 기본 실행 결과는 content에 그대로 담기며, SDK는 함수 비즈니스 실패 본문을 보존합니다. 따라서 HTTP 200이고 외부 success=true여도 content.ok=false일 수 있습니다. 클라이언트는 실제 함수에 따라 내부 ok/error/reason 및 data 결과를 검사해야 하며, 외부 상태만 판단해서는 안 됩니다.
returnType은 Func 반환 표현을 제어하며 기본값은 raw입니다. ALL/raw/repr/jsonDumps 등의 적용 가능 여부는 Func 서비스 설명을 기준으로 합니다. repr/jsonDumps의 데이터는 문자열일 수 있으므로 일괄적으로 객체로 파싱해서는 안 됩니다. 반환되는 추가 진단 필드에는 요청 파라미터가 포함될 수 있으므로 실제 내용에 따라 처리하고, 자격 증명이 포함된 본문을 공개적으로 전달하지 마십시오.
중앙 Func 목록/실행 전 화이트리스트의 이전 SDK 적응은 업스트림 HTTP 상태만으로 실패를 판단하지 않습니다. JSON 딕셔너리는 ok=false 또는 숫자 0인 경우에만 비즈니스 오류를 트리거하며, 200이 아니지만 ok가 없거나 true이면 계속 data를 가져올 수 있습니다. 딕셔너리가 아니고 HTTP가 200이 아닌 경우에만 외부 함수 오류로 고정 보고합니다. 빈 카탈로그는 업스트림 서비스가 정상적으로 연결되었음을 단독으로 증명하지 않으므로, 이상 발생 시 관리자가 서비스 로그와 함께 확인해야 합니다.
더 많은 함수 설명은 Func 문서를 참고하십시오.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| funcBody | json | 선택적 JSON 객체입니다. 문자열/배열/null이 될 수 없으며, 제공하지 않으면 빈 객체로 호출하고 워크스페이스 식별자와 Token을 주입합니다. null 허용: False 예시: {"kwargs": {"your_name": "示例调用者"}, "options": {"returnType": "jsonDumps"}}획득 또는 입력 방법: 해당 함수의 description/definition 메타데이터에 따라 파라미터 값을 구성하며, 생략 시 워크스페이스 파라미터가 자동 주입됩니다. |
|
| funcBody.kwargs | json | 선택적 동적 JSON 객체이며 위치 args 배열은 지원하지 않습니다. workspace_uuid/workspace_token은 서버에서 강제로 덮어씁니다. null 허용: False 예시: {"your_name": "示例调用者"}획득 또는 입력 방법: 함수 파라미터 이름을 실제 비즈니스 값에 매핑하며, 예를 들어 your_name에는 문자열을 입력하고 {"default":...} 정의 객체를 입력하지 않습니다. |
|
| funcBody.options | json | 선택적 JSON 객체이며, 이 공개 선언에서는 returnType만 정의합니다. null 허용: False 예시: {"returnType": "jsonDumps"}획득 또는 입력 방법: 클라이언트 요구에 따라 해당 Func가 지원하는 반환 표현을 선택합니다. |
|
| funcBody.options.returnType | custom_enum | 선택적 custom_enum이며, 공개 열거형은 ALL/raw/repr/jsonDumps이고 기본값 raw는 Func 서비스 동작을 따릅니다. 대소문자는 서비스가 실제로 허용하는 값을 따릅니다. null 허용: False 선택 가능 값: ['ALL', 'raw', 'repr', 'jsonDumps'] 예시: jsonDumps획득 또는 입력 방법: 일반적으로 raw는 원본 결과를 읽고, jsonDumps는 JSON 텍스트에 사용합니다. 먼저 해당 함수 문서에 따라 선택하십시오. |
|
| funcId | string | Y | 필수 문자열입니다. 중앙 서비스 openapi 카테고리에서 노출되거나 허용 캐시에 남아 있는 함수여야 하며, 임의의 로컬 함수/스크립트 이름이 아닙니다. null 허용: False 예시: example__openapi.test획득 또는 입력 방법: 함수 목록의 content[].id에서 현재 허용되고 기능을 파악한 전체 ID를 선택합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/outer_function/execute' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"funcId":"example__openapi.test","funcBody":{"kwargs":{"your_name":"示例调用者"},"options":{"returnType":"jsonDumps"}}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | JSON | Func 실행 응답을 그대로 전달하며, 일반적으로 ok/data를 포함하는 객체입니다. 함수/표현에 따라 다를 수 있으며 통일된 성공 비즈니스 구조가 아닙니다. |
| content.ok | boolean | Func 서비스 비즈니스 실행 성공 표시이며 별도로 확인해야 합니다. 실패해도 외부 HTTP 200일 수 있습니다. |
| content.data | JSON | 함수가 반환한 데이터로, 형태는 함수와 returnType에 따라 달라집니다. 예시는 참고용일 뿐 고정된 result 키를 보장하지 않습니다. |
| content.error | JSON | Func 비즈니스 오류 값이며 실패 시 나타날 수 있고, Studio 외부 errorCode로 간주해서는 안 됩니다. |
| content.reason | string | Func 비즈니스 실패 분류로, 실제 값은 Func가 결정합니다. |
| content.message | JSON | Func 비즈니스 메시지이며 Studio 최상위 message와 다릅니다. |
| content.detail | JSON | Func 진단 정보(예: 실행 작업 ID)이며 매번 존재한다고 보장하지 않습니다. |
| content.traceId | string | Func 업스트림 추적 ID이며 존재할 수 있습니다. 최상위 traceId는 이번 Studio 호출의 추적입니다. |
| content.reqCost | JSON | Func가 제공하는 경우의 소요 시간 정보이며, 단위는 Func 서비스 버전에 따르고 Studio는 환산하지 않습니다. |
| content.reqTime | JSON | Func가 제공하는 경우의 요청 시간입니다. |
| content.respTime | JSON | Func가 제공하는 경우의 응답 시간입니다. |
| content.reqDump | JSON | Func가 제공하는 경우의 요청 진단 정보이며 실제 파라미터가 포함될 수 있으므로 내용에 따라 보관에 주의하십시오. |
| content.declaration | object 또는 null | 비어 있지 않은 딕셔너리 결과의 최상위 공통 선언입니다. 스칼라/빈 객체에는 강제로 추가되지 않습니다. |
{
"code": 200,
"content": {
"ok": true,
"data": {
"result": "예시 호출 결과"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
함수 비즈니스는 실패했지만 Studio 인터페이스 외부는 여전히 성공한 예시:
{
"code": 200,
"content": {
"ok": false,
"error": 599.3,
"reason": "EFuncFailed",
"message": "Calling Function failed",
"detail": {
"id": "FUNC-TASK-EXAMPLE"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
이 페이지는 Studio 파라미터/권한/연결 오류와 Func 내부 비즈니스 실패를 구분합니다. Func 비즈니스 오류는 모두 열거하지 않으며, HTTP 200의 content.ok=false 예시는 래핑 경계만 설명하고 구체적인 error/reason은 실제 함수가 결정합니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 타입과 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | 요청 본문이 JSON 객체가 아님 | 일부 json 파일 형식 오류 | funcId와 선택적 funcBody 객체를 제출하십시오. |
| 403 | ft.Forbidden | 대상 함수가 중앙 openapi 카탈로그에 없고 허용 캐시도 없거나, 워크스페이스 Token 액세스 컨텍스트가 허용되지 않음 | 작업 권한이 없습니다 | 현재 카탈로그에서 전체 ID를 다시 선택하고, 로컬 함수 이름을 허용된 함수로 간주하지 마십시오. |
| 404 | ft.WKSPTokenNotExist | 현재 워크스페이스에 사용 가능한 보고 Token 없음 | 워크스페이스에 Token이 존재하지 않습니다 | 관리자에게 워크스페이스 Token 구성을 확인하도록 요청하고, 위조된 workspace_token을 전달하여 우회하지 마십시오. |
| 400 | ft.OuterFuncFailed | 실행 전 화이트리스트 목록이 딕셔너리 ok=false를 반환(특수 reason은 별도 매핑)하거나, 딕셔너리가 아니고 HTTP가 200이 아님 | 외부 함수 호출 실패 | 중앙 서비스와 대상 함수를 확인하십시오. 실제 실행 단계의 비즈니스 실패는 일반적으로 content 내에서 확인합니다. |
| 500 | ft.InternalServerError | 연결 타임아웃, 유효하지 않은 JSON/비JSON 본문 래핑 불가, 워크스페이스 Token 저장 이상 또는 기타 처리되지 않은 오류 | 내부 오류 | 먼저 대상 함수가 이미 비즈니스 동작을 완료했는지 확인하고, traceId와 실제 Func 작업 정보를 보관한 뒤 재시도 여부를 결정하십시오. |
| 400 | ft.SameSetTraggerExists | 중앙 Func 목록/화이트리스트가 ok=false를 반환하고 reason이 EBizCondition.DuplicatedCrontabConfig | 동일한 구성의 트리거가 이미 존재합니다 | 이것은 공유 SDK 특정 오류 매핑입니다. 업스트림 실제 응답과 구성을 확인하고, 이 페이지의 요청만으로 함수가 존재하지 않는다고 판단하지 마십시오. |