外部関数の実行¶
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 で、デフォルトは Func サービスの動作に従い raw です。大文字/小文字はサービスが実際に受け入れる形式に従います。 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 固有のエラーマッピングです。上流の実際のレスポンスと設定を確認し、本ページのリクエストだけで関数が存在しないと判断しないでください。 |