콘텐츠로 이동

외부 함수 실행



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 특정 오류 매핑입니다. 업스트림 실제 응답과 구성을 확인하고, 이 페이지의 요청만으로 함수가 존재하지 않는다고 판단하지 마십시오.

문서 평가

이 페이지가 도움이 되었나요?