インデックスをバインド¶
POST /api/v1/log_index_cfg/bind
概要¶
外部ログストレージリソースをバインドします。
呼び出し前の準備と使用手順¶
事前に外部ストレージでクエリ権限、実際のターゲットリソース、フィールドマッピングを準備し、その後 storeType を選択してこのワークスペースで一意のエイリアスにバインドします。ここではクエリアクセス設定のみを作成し、外部 Logstore/インデックス/テーブルは作成せず、外部データを現在のワークスペースへコピーすることもありません。SLS/TLS ではリソースをクエリして検証します。その他のタイプでは先にアクセステストを実行します。
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 ラップを使用しません。バインド/変更では先にデータベースへ保存し、その後ダウンストリームに更新とキャッシュクリアを通知します。後続処理が失敗しても設定は既に保存されている可能性があるため、先に一覧/詳細と実際の外部クエリを確認してから再試行を判断してください。名前を変更すると、旧名の削除と新名の作成がそれぞれ通知されるため、呼び出し側のインデックス名を確認する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 を取得し、このインターフェースの DF-API-KEY で代替しないでください。 |
| accessCfg.ak | string | SLS の通常バインドでは sk と組み合わせて必要です。TLS では必須です。外部変更でも有効な AK を指定します。 null の許可: False 例: <EXTERNAL-AK>取得または入力方法: SLS/TLS リソースのアクセスキー 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 | 外部変更で省略または空文字列を指定すると旧パスワードの復元を試みます。パスワードのクリアとしては扱われません。パスワードのないターゲットでは、バインド時に実際の要件に応じて省略できます。 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 などではターゲットの認証要件に応じて指定します。外部変更で省略しても旧ユーザー名が保持される保証はないため、完全に指定し直す必要があります。 null の許可: False 例: reader取得または入力方法: ターゲットのクエリアカウント。このワークスペースのメンバーではありません。 |
|
| desc | string | 任意の説明。バインド時に省略すると空になり、外部変更時も省略するとクリアされます。1024 文字以内を推奨します。 空文字列の許可: True null の許可: False 例: 外部应用日志。取得または入力方法: 外部データのソースを説明します。 |
|
| extend | json | 任意。外部変更時に指定するとオブジェクト全体を置換し、省略すると保持されます。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 の権限がカバーするリージョンと一致することを確認します。 |
|
| storeType | string | Y | バインド時は必須。外部変更ではこのフィールドを宣言せず、ターゲットの既存 storeType を使用します。このインターフェースでストレージタイプを変更することはできません。ClickHouse の公開接続パラメータは限られています。説明を参照してください。 null の許可: False 例: es取得または入力方法: sls/es/opensearch/beaver/volctls/clickhouse から選択します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/log_index_cfg/bind' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"external_app_logs","desc":"外部应用日志。","storeType":"es","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 | 無料/トライアル版ではバインドをサポートしていません | 現在のワークスペースバージョンではサポートされていません | バージョンがサポートしていることを確認してから接続してください。 |
| 403 | ft.Forbidden | 権限が不足しているか、現在のバージョンでこのインターフェースが許可されていません | 操作する権限がありません | 対応するインデックス権限を持つ API Key とサポート対象バージョンを使用してください。 |