バインドインデックス設定の変更¶
POST /api/v1/external_log_index_cfg/{cfg_uuid}/modify
概要¶
既存の外部バインドインデックスおよびアクセス設定を変更します。
呼び出し前の確認と使用手順¶
まずログインデックスのリストから外部バインドの cfg_uuid を選択し、詳細を読んで元の storeType、外部リソース、フィールドマッピングを確認してください。本 API は対象の元のタイプに従って検証し、storeType のタイプ変更は受け付けません。name/exterStoreName/accessCfg は完全なオブジェクトを指定する必要があります。desc を省略するとクリアされます。extend を指定すると全体が置換され、未指定の場合は保持されます。パスワード/SK を省略または空値にした場合は古い機密値を再設定しようとしますが、その他のアクセスキーは自動マージされません。新しい URL だけを送信しないでください。fields を省略した場合は保持され、[] またはすべて空のマッピングでも既存のマッピングはクリアされません。
SLS では project/logstore/region と AK/SK が必要です。TLS では project/topic 名、region、iamProjectName/projectId/topicId、AK/SK が必要です。ES/OpenSearch/Beaver では少なくとも URL が必要で、認証は対象の要件に従います。ClickHouse の公開パラメータでは exterStoreProject を通じてデータベースを指定でき、time フィールドのマッピングを必ず設定する必要があります。現在の公開 accessCfg には database/port/secure が宣言されていないため、内部 SDK オプションを直接渡すことはできず、現状はデフォルトの native 接続機能として処理されます。事前にデプロイ側で利用可能か確認してください。Beaver の条件には extend.conditionStr を使用します。
アクセスキーのフィールドは HTTPS 経由で元の値を送信し、フロントエンドの RSA ラッピングは使用しません。バインド/変更はまずデータベースに保存し、その後ダウンストリームに更新とキャッシュクリアを通知します。後続処理が失敗しても設定がすでに保存されている可能性があります。再試行を判断する前に、リスト/詳細および実際の外部クエリを確認してください。名前を変更すると、旧名の削除と新名の作成がそれぞれ通知されるため、呼び出し元のインデックス名を確認する必要があります。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| cfg_uuid | string | Y | パス設定 UUID であり、インデックス名ではありません。デフォルトインデックスは一部の変更のみ可能です。使用方法を参照してください。 例: lgim_example取得または入力方法: ログインデックスリスト の content.data[].uuid から本ワークスペースの設定を取得します。デフォルトインデックスは default を使用します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| extend.conditionStr | string | Beaver 条件文字列。バインドまたは外部変更で指定した場合は conditions として保存され、通常のインデックスの extend.filters 生成ルールは適用されません。 例: status=200取得または入力方法: Beaver のみ、そのストレージの実際のフィルタ構文に従って指定します。先に対象のクエリツールで検証してください。 |
|
| accessCfg | json | Y | 必須のアクセスオブジェクト。storeType に応じて以下のフィールドを指定します。OpenAPI では元の値を HTTPS 経由で送信し、コンソールの RSA ラッピングは使用しません。外部変更ではオブジェクト全体を置換し、一部の機密値のみ再設定できるため、変更したフィールドだけを送信しないでください。 null を許可: False 例: {"url": "https://logs.example.com", "username": "reader", "password": "<EXTERNAL-PASSWORD>"}取得または入力方法: 外部リソース管理者から最小クエリ権限のアカウント/AK を取得します。本 API の DF-API-KEY で代用しないでください。 |
| accessCfg.ak | string | SLS の通常バインドでは sk と組み合わせて指定する必要があります。TLS では必須です。外部変更でも有効な AK を指定してください。 null を許可: False 例: <EXTERNAL-AK>取得または入力方法: SLS/TLS リソースのアクセスキー ID。対応するクラウドリソースの認可から取得します。 |
|
| accessCfg.cloudAccountId | string | 外部変更のみで使用できる公開フィールドです。バインドの Body ではこのサブフィールドが宣言されていないため、初回バインドでは AK/SK 方式を使用し、宣言されていないパラメータを送信しないでください。 null を許可: False 例: cloud-account-example取得または入力方法: SLS の場合は、認可済みクラウドアカウント管理から対象にアクセス可能なクラウドアカウント ID を取得します。 |
|
| accessCfg.iamProjectDisplayName | string | TLS IAM プロジェクトの表示名。省略可能です。TLS では iamProjectName/projectId/topicId がすべて非空である必要があり、topicId がそのプロジェクトに属することをクエリで検証します。 空文字列を許可: True null を許可: False 例: 默认项目取得または入力方法: Volcengine TLS コンソールからリソースに対応する値を取得します。 |
|
| accessCfg.iamProjectName | string | TLS IAM プロジェクト名であり、project_name ではありません。TLS では iamProjectName/projectId/topicId がすべて非空である必要があり、topicId がそのプロジェクトに属することをクエリで検証します。 空文字列を許可: True null を許可: False 例: default取得または入力方法: Volcengine TLS コンソールからリソースに対応する値を取得します。 |
|
| accessCfg.password | string | 外部変更で省略または空文字列を指定すると古いパスワードの再設定を試みるため、パスワードのクリアとしては扱えません。パスワード不要の対象では、バインド時に実際の要件に応じて省略できます。 空文字列を許可: True null を許可: False 例: <EXTERNAL-PASSWORD>取得または入力方法: 対象アカウントのパスワード。HTTPS で送信します。例はプレースホルダーです。 |
|
| accessCfg.projectId | string | TLS プロジェクト ID。exterStoreProject 名に対応します。TLS では iamProjectName/projectId/topicId がすべて非空である必要があり、topicId がそのプロジェクトに属することをクエリで検証します。 空文字列を許可: True null を許可: False 例: project-example取得または入力方法: Volcengine TLS コンソールからリソースに対応する値を取得します。 |
|
| accessCfg.sk | string | SLS/TLS のシークレットキー。外部変更で省略/空文字列を指定すると古い SK の保持を試みるため、空値でクリアすることはできません。バインド時は完全に指定する必要があります。 null を許可: False 例: <EXTERNAL-SK>取得または入力方法: ak と組み合わせるシークレットキー。実際の値をログやドキュメントに記載しないでください。 |
|
| accessCfg.topicId | string | TLS ログトピック ID。exterStoreName 名に対応します。TLS では iamProjectName/projectId/topicId がすべて非空である必要があり、topicId がそのプロジェクトに属することをクエリで検証します。 空文字列を許可: True null を許可: False 例: topic-example取得または入力方法: Volcengine TLS コンソールからリソースに対応する値を取得します。 |
|
| accessCfg.url | string | 対応する接続タイプでは条件付き必須です。サーバー側でアクセステストを実行しますが、アドレスが有効なだけでは後続のすべてのクエリ権限を保証しません。 null を許可: False 例: https://logs.example.com取得または入力方法: ES/OpenSearch/Beaver の実際の接続アドレス。ClickHouse では管理者が提供する接続アドレスを使用します。 |
|
| accessCfg.username | string | ES などでは対象の認証要件に応じて指定します。外部変更で省略しても古いユーザー名が保持されるとは限らないため、完全に再設定する必要があります。 空文字列を許可: True null を許可: False 例: reader取得または入力方法: 対象のクエリ用アカウントであり、本ワークスペースのメンバーではありません。 |
|
| desc | string | 任意の説明。バインド時に省略すると空になり、外部変更時も省略するとクリアされます。1024 文字以内を推奨します。 空文字列を許可: True null を許可: False 例: 外部应用日志。取得または入力方法: 外部データのソースを説明します。 |
|
| extend | json | 任意。外部 modify で指定すると全体を置換し、省略すると保持されます。null は避けてください。Beaver の条件処理で 500 が発生する可能性があります。 null を許可: True 例: {}取得または入力方法: 外部インデックスの追加表示設定。Beaver のフィルタには conditionStr を使用できます。 |
|
| exterStoreName | string | Y | 必須の外部ターゲット名であり、ローカルの name 別名や設定 UUID ではありません。変更時は完全に指定する必要があります。 null を許可: False 例: app_logs取得または入力方法: 外部コンソールから実際のリソース名を取得します。SLS Logstore、TLS topic_name、ES/OpenSearch インデックス、Beaver ターゲット、または ClickHouse テーブル名です。 |
| exterStoreProject | string | SLS/TLS では条件付き必須で、ClickHouse では必須のデータベースソースです。通常の外部変更で指定しない場合は一部の古い値が保持されますが、SLS/TLS の検証では引き続き完全なプロジェクト設定が必要です。 null を許可: False 例: app_project取得または入力方法: SLS プロジェクト名、TLS project_name、ClickHouse データベース名。その他のタイプでは通常省略します。 |
|
| fields | array | 任意のマッピング配列。field と非空の originalField はそれぞれ一意である必要があります。originalField が空の項目は無視されます。TLS で time/__docid/message が不足している場合は同じ名前で自動補完されます。ClickHouse では time マッピングを明示する必要があります。外部変更では非空の有効なマッピングのみが置換に使用され、[] は古いマッピングをクリアしません。 null を許可: False 例: [{"field": "time", "originalField": "timestamp"}, {"field": "message", "originalField": "content"}]取得または入力方法: 対象の実際のフィールドからプラットフォームのクエリフィールドへのマッピングを選択します。詳細の isShowFields=true から既存のマッピングを確認します。 |
|
| fields[*] | object | マッピングオブジェクト。 例: {"field": "message", "originalField": "content"}取得または入力方法: 1 つのローカルクエリフィールドが 1 つの外部実フィールドに対応します。 |
|
| fields[*].field | string | 条件付き必須 | 宣言上必須で、非空かつ重複不可です。 null を許可: False 例: message取得または入力方法: 一般的なプラットフォームフィールド time/__docid/message、またはマッピングが必要なその他のキーです。 |
| fields[*].originalField | string | 条件付き必須 | 宣言上必須ですが、空文字列を渡すことは可能で、その項目は無視されます。古いマッピングの削除を意味しません。 空文字列を許可: True null を許可: False 例: content取得または入力方法: 外部ストレージ内の実際のフィールド名。たとえば content を message にマッピングします。 |
| isPublicNetworkAccess | boolean | 任意。SLS ではデフォルト false、ES/OpenSearch/Beaver/ClickHouse のバインドでは true で保存されます。null は避けてください。接続到達性の証明ではありません。 null を許可: True 例: false取得または入力方法: SLS では対象のアクセスネットワークに応じて選択します。プライベートネットワークの場合は、サイトが対象にアクセスできることを確認する必要があります。 |
|
| name | string | Y | 必須のローカルインデックス名。128 文字以内を推奨し、外部ストレージ名とは分けてください。外部変更ではこのローカル名を変更できます。 null を許可: False 例: external_app_logs取得または入力方法: 本ワークスペースのバインドインデックスに一意の別名を付けます。先にログインデックスのリストを確認してください。 |
| region | string | SLS/TLS では条件付き必須です。ES/OpenSearch/Beaver/ClickHouse のバインドでは空のリージョンに正規化されます。 null を許可: False 例: cn-hangzhou取得または入力方法: 対象クラウドリソースのコンソールから実際のリージョンコードを取得し、AK 権限の対象リージョンと一致することを確認します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/external_log_index_cfg/lgim_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"external_app_logs","desc":"外部アプリケーションログ。","exterStoreName":"app_logs","accessCfg":{"url":"https://logs.example.com","username":"reader","password":"<EXTERNAL-PASSWORD>"},"fields":[{"field":"time","originalField":"timestamp"},{"field":"message","originalField":"content"}]}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は true。認証情報や新しい設定は返さないため、リスト/詳細から読み戻す必要があります。 |
{
"code": 200,
"content": true,
"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 ファイル形式エラー | パラメータ表に従ってオブジェクトを送信し、storagePolicy には JSON オブジェクトを使用してください。 |
| 429 | ft.OperationTooFrequently | 同一ワークスペースでのストレージ書き込み/インデックス関係の同時操作、またはロックリースの失効 | 操作が頻繁すぎます。しばらくしてから再試行してください | 進行中の操作が完了するのを待ってバックオフ再試行し、先に現在の状態を確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、ダウンストリーム接続/通常の 5xx、またはフィールド形状の異常 | 内部エラー | まず設定を読み取り、実際のストレージの現在の状態を確認してください。失敗が続く場合は traceId を提供してください。エラーを未保存とみなしたり、そのまま重複して新規追加できると判断したりしないでください。 |
| 406 | ft.InvalidParameterValidation | 対応するストレージで必須の AK/SK/URL などの値が空 | {} の値が無効です。現在の値: {} |
storeType に応じて対応するアクセス設定を完全に指定してください。 |
| 406 | ft.DataStoreCfgAkSkOrAccountIdIsMissing | SLS で AK/SK が不足し、利用可能なクラウドアカウント ID もない | ストレージ設定パラメータエラー。ak/sk またはクラウドアカウント ID が不足しています | 初回の公開バインドでは完全な AK/SK を使用します。外部変更では公開フィールドに従ってクラウドアカウント ID を使用できます。 |
| 406 | ft.DataStoreCfgAkSkIsMissing | TLS で AK/SK が不足 | ストレージ設定パラメータエラー。ak/sk が不足しています | 対応するキーを指定してください。 |
| 406 | ft.InvalidTlsIamORProjectORTopic | TLS のプロジェクト/リージョン/トピック情報が不完全、またはトピック検証が不一致 | TLS の Iam/project/topic が無効 | 名前、ID、認可関係を確認してください。 |
| 400 | ft.CustomStoreLogstoreInvalid | SLS の対象が有効なクエリモードを返さない | 無効なカスタムクラウドリソース | Logstore の存在、タイプ、認可を確認してください。 |
| 400 | ft.TestExternalResourceAccessInvalid | SLS/TLS 以外のアクセス接続性テストが失敗 | テストに合格しませんでした。設定情報が正しいことを確認し、ネットワーク接続が正常であることを確保してください | ネットワーク、アドレス、対象へのアクセス権限を確認してください。 |
| 406 | ft.ObjectFieldNameRepeat | field が重複 | マッピング設定内のフィールド {} が重複しています |
各ターゲットフィールドには 1 件のマッピングのみ設定してください。 |
| 406 | ft.ObjectOriginalFieldNameRepeat | originalField が重複 | マッピング設定内のマッピングフィールド {} が重複しています |
各ソースフィールドは 1 回のみ使用してください。 |
| 400 | ft.ForIndexCfgNameExists | 本ワークスペースに同名のアクティブなインデックスが既に存在 | 指定されたインデックス設定名は既に存在します | 一意の別名を選択してください。 |
| 400 | ft.LogIndexCfgNameHasUsed | バインド別名が過去に使用された内部インデックス名と競合 | 指定されたインデックス設定名は使用済みです | 別名を変更し、内部の過去名を再利用しないでください。 |
| 400 | ft.WKSPTypeUnsupportAction | 無料/体験版ではバインドをサポートしていない | 現在のワークスペースプランではサポートされていません | プランがサポートしていることを確認してから接続してください。 |
| 404 | ft.LogIndexCfgNoExists | 指定されたインデックス設定が存在しない/削除済み/別ワークスペース | 指定されたログインデックス設定は存在しません | リストから有効な外部バインド UUID を再取得してください。 |
| 404 | ft.ObjectNotExists | 機密値の再設定時に関連するアクセス設定が存在しない | 指定されたオブジェクトは存在しません | バインドのライフサイクルとアクセス設定を確認し、無闇に再作成しないでください。 |
| 404 | ft.NotFoundExternalResourceAccessCfg | 後続のアクセス設定変更時に対象が存在しない、または同時実行で消失 | 指定された外部インデックスのアクセス情報設定が見つかりません | バインドのライフサイクルを確認し、管理者が対応してください。デフォルトインデックスで代用しないでください。 |
| 403 | ft.Forbidden | 権限不足、または現在のプランでこの API が許可されていない | 操作権限がありません | 対応するインデックス権限を持つ API Key とサポート対象のプランを使用してください。 |