共有¶
POST /api/v1/snapshots/{snapshot_uuid}/share
概要¶
既存のスナップショットに対してアクセス共有と長期初回リダイレクトコードを作成します。
呼び出し前の準備と使用手順¶
現在の Key には share.shareManage が必要で、現在のワークスペース内の削除されていないスナップショットのみが対象です。無料プランのワークスペースはスナップショット共有をサポートしません。詳細はサイトのバージョンによって判断されます。共有設定を作成するたびに新しい設定が作成され、公開された冪等キーはありません。重複リクエストにより複数の有効な共有が作成される可能性があります。タイムアウト/500 の場合は、まず現在のコンソールの共有管理リストで resourceUUID を確認してから、再試行するか決定してください。
content.token と authCode は同一の長期初回リダイレクトコードであり、現在のワークスペースのブランド/カスタムコンソールドメインの /share/{code} ページで使用されます。データクエリに直接使用できる2段階共有トークンではなく、ましてや share_ 設定 UUID でもありません。shortUrl はサイトで短縮リンクが無効な場合に空になる可能性があるため、実際のコンソール入口を使用して /share/ と authCode を連結してください。ブランドドメインをハードコードしないでください。共有を解除するには、コンソールの共有管理から該当する share_ UUID を取得する必要があります。現在の作成レスポンスはこの UUID を返さず、この OpenAPI グループにも ShareConfig の公開リストはないため、今回返された code だけから UUID を導出することはできません。UI に表示されない場合は、ワークスペース管理者に取得を依頼してください。クロスワークスペース認可設定の grant_ UUID は使用できず、token や snap_ を渡すこともできません。
今回保存するスナップショットページ設定のコピーは表示用であり、実際のクエリは引き続きスナップショット保存時のサーバー側範囲を復元します。クライアントの maskCfg は追加のマスキングのみを行い、認可を拡大することはできません。共有正規表現は文字列値のみを処理し、数値/オブジェクト/配列はこのルールでマスクされません。fields=* は単独で使用する必要があり、*,message を混在させても全フィールドがカバーされる保証はありません。保存時の正規表現検証は regex を使用しますが、実行時は Python 標準の re.sub を使用するため、両方でサポートされる構文を使用し、実際のサンプルで検証してください。保存に成功してもクエリが実行可能である保証はありません。古いスナップショットで範囲が欠落している/サポートされていないクエリは、アクセス時に 403 となり、元の共有者に再生成を求める場合があります。共有の作成に成功しても、各クエリが利用可能である保証はありません。
IP 制御は現在 custom のみが公開宣言を実際に通過できます。followWorkspace は長さ検証の競合により 406 になります。isOpen=true、type=custom、および空でない実際の IP リストが必須です。custom[] は実際には制限しません。抽出コード/有効期限とマスキングによって、必要に応じてアクセスを制御します。hiddenTopBar/showWatermark は表示のみです。短縮リンクと初回リダイレクトコードのキャッシュ同期は、本体送信の前後に行われる可能性があります。500 でも有効な共有が存在しない保証はないため、先に確認してから再試行してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| snapshot_uuid | string | Y | 共有設定の share_ UUID、token/authCode の初回リダイレクトコード、またはダッシュボード UUID ではありません。 例: snap_example取得/入力方法: スナップショットリスト から content.data[].uuid を取得し、現在の Key で管理権限が確認できる snap_ UUID のみを操作します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得/入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエスト Body パラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| maskCfg | object | 任意のオブジェクト。正しい fields/reExprs を同時に構築する必要があります。共有時の追加マスキングであり、スナップショット生成時に取得されたデータ/機密ルールを置き換えるものではありません。実データ全体がカバーされることを自動検証するものではありません。 例: {"fields": "message", "reExprs": [{"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}]}取得/入力方法: 表示する実際のフィールドとマスキングパターンに従って構築し、まず制御されたデータで検証してください。 |
|
| maskCfg.fields | string | 任意の文字列。省略/空の場合は共有マスキングフィールドを指定しません。先頭と末尾の空白はフィールドごとに strip されます。一致する文字列値のみが有効化された正規表現を実行し、数値/オブジェクト/配列はこの共有正規表現による変換マスキングの対象になりません。アクセス許可リストではありません。 空文字列を許可: True null を許可: False 例: message,host取得/入力方法: スナップショットクエリで実際に返される列名からフィールドを選択し、カンマで区切ります。すべてのフィールドを指定する場合は * を単独で渡し、*,message のような混在リストを記述しないでください。 |
|
| maskCfg.reExprs | array | 任意のオブジェクト配列。省略時は []。作成時にすべての reExpr の構文を検査し、enable=0 の項目も含みます。子項目の不完全な宣言は検証対象となり、オブジェクト以外の場合は 500 になることがあります。 null を許可: False 例: [{"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}]取得/入力方法: 呼び出し元が検証済みの正規表現配列を提供します。 |
|
| maskCfg.reExprs[*] | json | オブジェクトには正しい reExpr と enable を含める必要があり、配列の順に適用されます。 例: {"name": "email", "reExpr": "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", "enable": 1}取得/入力方法: 1 件のマスキングルールです。 |
|
| maskCfg.reExprs[*].name | string | 任意の表示名。フィールドの選択には使用しません。 例: email取得/入力方法: 呼び出し元が正規表現に表示名を付けます。 |
|
| maskCfg.reExprs[*].reExpr | string | 保存時の検証には regex.finditer を使用し、実行時には標準の re.sub を使用します。両方に互換性が必要で、regex 固有の構文は保存に成功しても共有クエリ時にエラーになる可能性があります。保存時の検証に失敗すると 400 ErrorRegularExpression になります。実際の文字列サンプルとパフォーマンスを検証する必要があります。 例: [A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+取得/入力方法: Python 標準の re.sub と互換性のある式を入力し、実際のサンプルで検証してください。 |
|
| maskCfg.reExprs[*].enable | integer | 実行時は真偽値で実行可否を判断します。0/1 の整数を推奨します。列挙は完全には宣言されていないため、任意の型に依存して安定した動作を期待しないでください。 例: 1取得/入力方法: 0 は無効、1 は有効です。 |
|
| ipWhitelistSet | object | 任意の IP 制御オブジェクト。省略/無効の場合、共有 IP 制限は付加されません。作成時に IP 文字列を完全には検証しません。実際のアクセス経路で受け入れてください。 例: {"isOpen": true, "type": "custom", "ipWhitelist": ["192.0.2.0/24"]}取得/入力方法: ネットワーク管理者が、共有でアクセスを許可する実際の出口 IP/CIDR を提供します。例のアドレスは置き換える必要があります。 |
|
| ipWhitelistSet.ipWhitelist | array | 任意の配列。custom の場合は明示的に空でない必要があります。[] は現在実際には制限せず、すべてを拒否するわけではありません。項目ごとの作成時検証はなく、無効なアドレスはアクセス時に例外となる可能性があるため、必ず検証してください。 null を許可: False 例: ["192.0.2.0/24"]取得/入力方法: ネットワーク管理者が指定した単一 IP または CIDR セグメント。サーバー側が認識する実際のクライアント出口アドレスを確認してください。 |
|
| ipWhitelistSet.isOpen | boolean | 任意のブール値。省略時は false。true の場合でも、有効な type を選択し、空でないリストを提供しない限り、期待どおりに制限されません。 null を許可: False 例: true取得/入力方法: 共有の受信ネットワークを制限する必要がある場合は明示的に true にします。 |
|
| ipWhitelistSet.type | string | 列挙として custom/followWorkspace を宣言していますが、followWorkspace は 15 文字で、現在の maxLength 12 と競合するため事前に 406 になります。この公開入口からは設定できません。省略/空で isOpen=true の場合、実行時に警告のみで制限されない可能性があるため、デフォルトでワークスペースに追従する項目として扱わないでください。 空文字列を許可: True null を許可: False 選択可能な値: ['followWorkspace', 'custom'] 最大長: 12 例: custom取得/入力方法: 現在の公開書き込みでは custom を使用してください。 |
|
| ipWhitelistSet.ipWhitelist[*] | string | 単一の IP/ネットワークセグメント文字列。ドメイン名や URL ではありません。 例: 192.0.2.0/24取得/入力方法: 実際に許可する出口 IP/CIDR。例のネットワークセグメントは形式を示すためのものです。 |
|
| changeTime | boolean | 任意のブール値。デフォルトの UI では false として扱われます。表示制御のみを保存し、サーバー側の認可範囲/元データの保持期間を拡大しません。 null を許可: False 例: false取得/入力方法: 共有アクセス者が UI でクエリ時間を調整できるかどうかで決定します。 |
|
| expirationAt | integer | 任意の整数。省略時はサイトの snapshotShareCfg.effectiveTime(デフォルト 172800 秒 = 2 日)に従います。-1 は無期限です。明示的な空文字列は許可が宣言されていても -1 に正規化されるため、整数のみを推奨します。過去の時刻は保存できますが、アクセス時点で期限切れとなります。Unix ミリ秒ではありません。 空文字列を許可: True null を許可: False 例: -1取得/入力方法: 呼び出し元が有効期間を Unix 秒で選択します。-1 は無期限で、無期限以外は現在時刻に希望する有効秒数を加算した値を指定します。 |
|
| extractionCode | string | 任意の文字列。省略/空の場合は抽出コードを付加しません。DF-API-KEY や共有初回リダイレクト authCode ではありません。サーバー側に抽出コードを保存するため、公開ログに記録しないでください。 空文字列を許可: True null を許可: False 最大長: 12 例: read123取得/入力方法: 呼び出し元が 1~12 文字の抽出コードを生成し、制御されたチャネルで受信者に通知します。 |
|
| hiddenTopBar | boolean | 任意のブール値。デフォルトは false。Body は Query 値を上書きして互換性を保ちます。ページ上部バーのみを制御し、認証ではありません。 null を許可: False 例: false取得/入力方法: 共有ページの表示要件に応じて選択します。 |
|
| showWatermark | boolean | 任意のブール値。デフォルトの UI では false。ウォーターマークはデータアクセス制限の代替ではありません。 null を許可: False 例: false取得/入力方法: 共有の表示要件に応じて選択します。 |
パラメータ補足説明¶
スナップショットはページ設定とサーバー側のクエリ範囲を保存します。インターネット共有では別途共有設定を作成する必要があり、snap_、share_、初回リダイレクトコード、2段階トークンはそれぞれ異なる識別子です。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/snapshots/snap_example/share' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"expirationAt":-1,"extractionCode":"read123","changeTime":false,"hiddenTopBar":false,"showWatermark":true,"ipWhitelistSet":{"isOpen":true,"type":"custom","ipWhitelist":["192.0.2.0/24"]}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 共有作成結果。share_ 設定 UUID/完全なスナップショットは含みません。 |
| content.token | string | 長期初回リダイレクトコードの互換フィールド。authCode と同じで、2段階クエリトークンではありません。 |
| content.authCode | string | 同一の長期初回リダイレクトコード。コンソールの /share/{code} にアクセスします。有効期限は共有設定に従います。 |
| content.shortUrl | string | 生成された短縮リンクの完全な URL。無効/未返却の場合は空で、コンソールの元の共有アドレスを使用する必要があります。 |
| content.isHidden | boolean | この公開作成では false。isHidden の入力は受け付けません。 |
| content.declaration | object または null | 現在のワークスペースの公開宣言。 |
{
"code": 200,
"content": {
"token": "SHARE-LINK-CODE",
"authCode": "SHARE-LINK-CODE",
"shortUrl": "",
"isHidden": false,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーの詳細は共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | 共有パラメータオブジェクトを送信してください。 |
| 404 | ft.ObjectNotExists | 現在のワークスペースに対象スナップショットが存在しない/削除済みです | 指定オブジェクトが存在しません | このワークスペースのスナップショットリストから snap_ UUID を再取得してください。 |
| 401 | ft.WKSPNotExistOrReleased | 共有作成時に現在のアクティブワークスペースの検証に失敗/ワークスペースが解放済みです | ワークスペースが存在しない/または解放済みです | まず現在の Key のワークスペースのアクティブ状態を確認してください。ブランドアドレスのみを構築する NotFoundWorkspace とは異なり、既存のページリンクでワークスペースが有効であることを証明する必要はありません。 |
| 403 | ft.ForbiddenFreeWKSPSnapshotShare | 現在のワークスペースがスナップショット共有をサポートしない無料プランです | 無料プランのワークスペースではスナップショット共有が禁止されています | 管理者が製品バージョンを確認してください。isHidden などの未公開パラメータで回避しないでください。 |
| 403 | ft.ShareTokenInvalid | スナップショットを事前に確認した後、共有作成でリソースを再度読み取る際に無効になっています | 共有リソースが無効です | スナップショットの状態を更新し、削除済みか確認してください。 |
| 406 | ft.NotFoundWorkspace | ブランド/カスタムドメインでコンソールアドレスを構築する際にワークスペースが存在しません | 指定されたワークスペースが見つかりません | 管理者が Key のワークスペースとアクセスドメイン設定を確認してください。 |
| 400 | ft.ErrorRegularExpression | maskCfg.reExprs 内の任意の正規表現がコンパイルできません。無効化された項目も含みます | 正規表現に誤りがあります | まずすべての正規表現を検証し、無効な項目を削除してから再作成してください。 |
| 500 | ft.InternalServerError | 履歴スナップショットの content/meta 構造、共有/初回リダイレクト資格情報の書き込み、短縮リンク生成、または送信後の資格情報キャッシュ同期で未処理の例外が発生しました | 内部エラー | まずコンソールの共有管理で作成済みか確認してから再試行を決定し、複数の有効な共有が生成されるのを避けてください。traceId を保持して調査してください。 |