変換APIの更新

変換の特定のプロパティを更新します。

リクエスト

POST _transform/<transform_id>/_update

前提条件

次の権限が必要です：

  • クラスター: manage_transform（transform_admin ビルトインロールがこの権限を付与します）
  • ソースインデックス: read, view_index_metadata
  • 宛先インデックス: read, index。retention_policy が構成されている場合、delete インデックス権限も必要です。

説明

このAPIは既存の変換を更新します。更新できるプロパティのリストは、変換を作成する際に定義できるリストのサブセットです。

変換が更新されると、一連の検証が行われて成功を確保します。defer_validation パラメータを使用してこれらのチェックをスキップできます。

説明を除くすべての更新されたプロパティは、変換が次のチェックポイントを開始するまで有効になりません。これは、各チェックポイントでデータの一貫性を保つためです。

  • 変換は、更新時にユーザーが持っていた役割を記憶し、その権限で実行されます。 二次認証ヘッダーを提供した場合、それらの資格情報が代わりに使用されます。
  • 変換を更新するにはKibanaまたはこのAPIを使用する必要があります。内部、システム、または隠しインデックスを直接更新することはサポートされておらず、永続的な失敗を引き起こす可能性があります。

パスパラメータ

  • <transform_id>
  • （必須、文字列）変換の識別子。

クエリパラメータ

  • defer_validation
  • （オプション、ブール値）true の場合、遅延検証は実行されません。この動作は、ソースインデックスが変換が更新された後に存在する場合に望ましい場合があります。
  • timeout
  • （オプション、時間）応答を待つ期間。タイムアウトが切れる前に応答が受信されない場合、リクエストは失敗し、エラーが返されます。デフォルトは 30s です。

リクエストボディ

  • description

  • （オプション、文字列）変換の自由形式の説明。

  • dest

  • （オプション、オブジェクト）変換の宛先。
    dest のプロパティ
    • index
    • （必須、文字列）変換の宛先インデックス。
      pivot 変換の場合、宛先インデックスのマッピングは可能な限りソースフィールドに基づいて推測されます。代替マッピングが必要な場合は、変換を開始する前に インデックス作成API を使用してください。
      latest 変換の場合、マッピングは決して推測されません。宛先インデックスの動的マッピングが望ましくない場合は、変換を開始する前に インデックス作成API を使用してください。
    • aliases
    • （オプション、オブジェクトの配列）変換の宛先インデックスが持つべきエイリアス。エイリアスは変換の保存された資格情報を使用して操作され、これは作成時に提供された二次資格情報を意味します（プライマリおよび二次資格情報が指定されている場合）。
      宛先インデックスは、変換によって作成されたか、ユーザーによって事前に作成されたかに関係なく、エイリアスに追加されます。
  • aliases のプロパティ
    詳細
    • alias
    • （必須、文字列）エイリアスの名前。
    • move_on_creation
    • （オプション、ブール値）宛先インデックスがこのエイリアスの唯一のインデックスであるべきかどうか。true の場合、宛先インデックスをこのエイリアスに追加する前に、他のすべてのインデックスがこのエイリアスから削除されます。デフォルトは false です。
    • pipeline
    • （オプション、文字列）インジェストパイプライン の一意の識別子。
  • frequency

  • （オプション、時間単位）変換が継続的に実行されているときにソースインデックスの変更をチェックする間隔。最小値は 1s で、最大値は 1h です。デフォルト値は 1m です。

  • _meta

  • （オプション、オブジェクト）オプションの変換メタデータを定義します。

  • retention_policy

  • （オプション、オブジェクト）変換の保持ポリシーを定義します。定義された基準を満たすデータは宛先インデックスから削除されます。
    retention_policy のプロパティ

    • time
    • （必須、オブジェクト）変換が保持ポリシーを設定するために時間フィールドを使用することを指定します。保持ポリシーの time.field が存在し、max.age より古いデータを含む場合、データは削除されます。
      time のプロパティ
      • field
      • （必須、文字列）ドキュメントの年齢を計算するために使用される日付フィールド。time.field を既存の日付フィールドに設定します。
      • max_age
      • （必須、時間単位）宛先インデックス内のドキュメントの最大年齢を指定します。設定された値より古いドキュメントは宛先インデックスから削除されます。

  • settings

  • （オプション、オブジェクト）オプションの変換設定を定義します。
    settings のプロパティ

    • align_checkpoints
    • （オプション、ブール値）変換のチェックポイント範囲がパフォーマンスのために最適化されるべきかどうかを指定します。このような最適化は、変換設定で日付ヒストグラムがグループソースとして指定されている場合、チェックポイント範囲を日付ヒストグラムの間隔に合わせることができます。その結果、宛先インデックス内のドキュメントの更新が少なくなり、全体的なパフォーマンスが向上します。デフォルト値は true で、これは可能な場合にチェックポイント範囲が最適化されることを意味します。
    • dates_as_epoch_millis
    • （オプション、ブール値）出力の日付がISO形式の文字列（デフォルト）またはエポックからのミリ秒として書き込まれるべきかどうかを定義します。epoch_millis は、7.11 バージョン以前に作成された変換のデフォルトでした。互換性のある出力を得るには、これを true に設定します。デフォルト値は false です。
    • deduce_mappings
    • （オプション、ブール値）変換が宛先インデックスのマッピングを変換設定から推測するべきかどうかを指定します。デフォルト値は true で、これは可能な場合に宛先インデックスのマッピングが推測されることを意味します。
    • docs_per_second
    • （オプション、浮動小数点数）1秒あたりの入力ドキュメントの数の制限を指定します。この設定は、検索リクエストの間に待機時間を追加することによって変換を制限します。デフォルト値は null で、これは制限を無効にします。
    • max_page_search_size
    • （オプション、整数）各チェックポイントの合成集約に使用する初期ページサイズを定義します。サーキットブレーカー例外が発生した場合、ページサイズは動的に低い値に調整されます。最小値は 10 で、最大値は 65,536 です。デフォルト値は 500 です。
    • num_failure_retries
    • （オプション、整数）変換タスクが failed としてマークされる前に、回復可能な失敗に対しての再試行回数を定義します。最小値は 0 で、最大値は 100 です。-1 は無限を示すために使用できます。この場合、変換は回復可能な失敗の再試行を決してあきらめません。デフォルト値はクラスターの設定 num_transform_failure_retries です。
    • unattended
    • （オプション、ブール値）true の場合、変換は無人モードで実行されます。無人モードでは、変換はエラーが発生した場合に無限に再試行され、変換は決して失敗しません。無限以外の再試行回数を設定すると、検証に失敗します。デフォルトは false です。

  • source

  • （オプション、オブジェクト）変換のデータソース。
    source のプロパティ

    • index
    • （必須、文字列または配列）変換のソースインデックス。単一のインデックス、インデックスパターン（例："my-index-*"）、インデックスの配列（例：["my-index-000001", "my-index-000002"]）、またはインデックスパターンの配列（例：["my-index-*", "my-other-index-*"]）である可能性があります。リモートインデックスの場合は、"remote_name:index_name" 構文を使用します。
      リモートクラスターにインデックスがある場合、マスターノードと少なくとも1つの変換ノードは remote_cluster_client ノードロールを持っている必要があります。
    • query
    • （オプション、オブジェクト）ソースインデックスからデータのサブセットを取得するクエリ句。 クエリDSLを参照してください。

  • sync

  • （オプション、オブジェクト）変換が継続的に実行されるために必要なプロパティを定義します。
    これらのプロパティは、継続的な変換の場合にのみ更新できます。バッチ変換を継続的な変換に変更したり、その逆を行ったりすることはできません。代わりに、Kibanaで変換をクローンし、sync プロパティを追加または削除します。
    sync のプロパティ
    • time
    • （必須、オブジェクト）変換がソースインデックスと宛先インデックスを同期させるために時間フィールドを使用することを指定します。
      time のプロパティ
      • delay
      • （オプション、時間単位）現在の時間と最新の入力データ時間の間の時間遅延。デフォルト値は 60s です。
      • field
      • （必須、文字列）ソース内の新しいドキュメントを識別するために使用される日付フィールド。
        一般的に、インジェストタイムスタンプを含むフィールドを使用することが良いアイデアです。異なるフィールドを使用する場合、データ伝送遅延を考慮するように delay を設定する必要があるかもしれません。

例

Python

  1. resp = client.transform.update_transform(
  2.    transform_id="simple-kibana-ecomm-pivot",
  3.    source={
  4.    "index": "kibana_sample_data_ecommerce",
  5.    "query": {
  6.    "term": {
  7.    "geoip.continent_name": {
  8.    "value": "Asia"
  9.    }
  10.    }
  11.    }
  12.    },
  13.    description="Maximum priced ecommerce data by customer_id in Asia",
  14.    dest={
  15.    "index": "kibana_sample_data_ecommerce_transform_v2",
  16.    "pipeline": "add_timestamp_pipeline"
  17.    },
  18.    frequency="15m",
  19.    sync={
  20.    "time": {
  21.    "field": "order_date",
  22.    "delay": "120s"
  23.    }
  24.    },
  25. )
  26. print(resp)

Ruby

  1. response = client.transform.update_transform(
  2.   transform_id: 'simple-kibana-ecomm-pivot',
  3.   body: {
  4.    source: {
  5.    index: 'kibana_sample_data_ecommerce',
  6.    query: {
  7.    term: {
  8.    'geoip.continent_name' => {
  9.    value: 'Asia'
  10.    }
  11.    }
  12.    }
  13.    },
  14.    description: 'Maximum priced ecommerce data by customer_id in Asia',
  15.    dest: {
  16.    index: 'kibana_sample_data_ecommerce_transform_v2',
  17.    pipeline: 'add_timestamp_pipeline'
  18.    },
  19.    frequency: '15m',
  20.    sync: {
  21.    time: {
  22.    field: 'order_date',
  23.    delay: '120s'
  24.    }
  25.    }
  26.   }
  27. )
  28. puts response

Js

  1. const response = await client.transform.updateTransform({
  2.   transform_id: "simple-kibana-ecomm-pivot",
  3.   source: {
  4.    index: "kibana_sample_data_ecommerce",
  5.    query: {
  6.    term: {
  7.    "geoip.continent_name": {
  8.    value: "Asia",
  9.    },
  10.    },
  11.    },
  12.   },
  13.   description: "Maximum priced ecommerce data by customer_id in Asia",
  14.   dest: {
  15.    index: "kibana_sample_data_ecommerce_transform_v2",
  16.    pipeline: "add_timestamp_pipeline",
  17.   },
  18.   frequency: "15m",
  19.   sync: {
  20.    time: {
  21.    field: "order_date",
  22.    delay: "120s",
  23.    },
  24.   },
  25. });
  26. console.log(response);

コンソール

  1. POST _transform/simple-kibana-ecomm-pivot/_update
  2. {
  3.   "source": {
  4.    "index": "kibana_sample_data_ecommerce",
  5.    "query": {
  6.    "term": {
  7.    "geoip.continent_name": {
  8.    "value": "Asia"
  9.    }
  10.    }
  11.    }
  12.   },
  13.   "description": "Maximum priced ecommerce data by customer_id in Asia",
  14.   "dest": {
  15.    "index": "kibana_sample_data_ecommerce_transform_v2",
  16.    "pipeline": "add_timestamp_pipeline"
  17.   },
  18.   "frequency": "15m",
  19.   "sync": {
  20.    "time": {
  21.    "field": "order_date",
  22.    "delay": "120s"
  23.    }
  24.   }
  25. }

変換が更新されると、更新された構成が受信されます：

コンソール-結果

  1. {
  2.   "id" : "simple-kibana-ecomm-pivot",
  3.   "authorization" : {
  4.    "roles" : [
  5.    "superuser"
  6.    ]
  7.   },
  8.   "version" : "8.4.0",
  9.   "create_time" : 1656113450613,
  10.   "source" : {
  11.    "index" : [
  12.    "kibana_sample_data_ecommerce"
  13.    ],
  14.    "query" : {
  15.    "term" : {
  16.    "geoip.continent_name" : {
  17.    "value" : "Asia"
  18.    }
  19.    }
  20.    }
  21.   },
  22.   "dest" : {
  23.    "index" : "kibana_sample_data_ecommerce_transform_v2",
  24.    "pipeline" : "add_timestamp_pipeline"
  25.   },
  26.   "frequency" : "15m",
  27.   "sync" : {
  28.    "time" : {
  29.    "field" : "order_date",
  30.    "delay" : "120s"
  31.    }
  32.   },
  33.   "pivot" : {
  34.    "group_by" : {
  35.    "customer_id" : {
  36.    "terms" : {
  37.    "field" : "customer_id"
  38.    }
  39.    }
  40.    },
  41.    "aggregations" : {
  42.    "max_price" : {
  43.    "max" : {
  44.    "field" : "taxful_total_price"
  45.    }
  46.    }
  47.    }
  48.   },
  49.   "description" : "Maximum priced ecommerce data by customer_id in Asia",
  50.   "settings" : { }
  51. }