diff --git a/ja_JP/access-control/authz/mnesia.md b/ja_JP/access-control/authz/mnesia.md index d814e8007..2ef5acf6d 100644 --- a/ja_JP/access-control/authz/mnesia.md +++ b/ja_JP/access-control/authz/mnesia.md @@ -1,6 +1,6 @@ # 組み込みデータベースの使用 -EMQX は、組み込みデータベースを通じて低コストで即時に利用可能な認可ルールの保存方法を提供します。Dashboard または設定ファイルで組み込みデータベース（Mnesia）をデータソースとして設定し、Dashboard または HTTP API を通じて関連する認可チェックルールを追加できます。 +EMQX は、組み込みデータベースを通じて低コストかつすぐに使える認可ルールの保存方法をユーザーに提供しています。Dashboard または設定ファイルで組み込みデータベース（Mnesia）をデータソースとして設定し、Dashboard または HTTP API を通じて関連する認可チェックルールを追加できます。 ::: tip 前提条件 @@ -14,13 +14,13 @@ EMQX は、組み込みデータベースを通じて低コストで即時に利 2. 右上の **Create** をクリックし、**Backend** に **Built-in Database** を選択して **Next** をクリックします。 - 組み込みデータベース認可設定画面 + authz-mnesia_ee -3. 組み込みデータベース認可は設定パラメータを必要としないため、**Create** をクリックして完了します。 +3. 組み込みデータベース認可は設定パラメータが不要なため、**Create** をクリックして完了します。 ## 設定ファイルでの設定 -組み込みデータベースの認可機能は、`type` が `built_in_database` で識別されます。 +組み込みデータベース認可は `type` が `built_in_database` で識別されます。 設定例： @@ -33,54 +33,141 @@ EMQX は、組み込みデータベースを通じて低コストで即時に利 - `type`: 認可チェッカーのデータソースタイプ。ここでは `built_in_database` を指定します。 -- `enable`: このチェッカーを有効にするかどうか。オプション値は `true` または `false`。 +- `enable`: このチェッカーを有効にするかどうか。オプション値は `true`、`false`。 ## 認可ルールの作成 -認可ルールは Dashboard または API を通じて作成できます。 +認可ルールは Dashboard または API から作成できます。 ### Dashboard での作成 Dashboard の **Authorization** ページで、**Built-in Database** バックエンドの **Actions** 列にある **Permissions** ボタンをクリックします。 -組み込みデータベース認可ルール設定画面 +authz-config-built-in-rules_ee クライアント ID、ユーザー名、またはトピックに基づいて認可チェックを設定できます。 - **Client ID**: **Client ID** タブで、このルールを適用するクライアントを指定します。 - **Username**: **Username** タブで、このルールを適用するユーザーを指定します。 -- **Permission**: 現在のクライアント／ユーザーからの特定の操作リクエストを許可するか拒否するか。オプション値は **Allow** または **Deny**。 -- **Action**: このルールに対応する操作を設定。オプション値は **Publish**、**Subscribe**、**Publish & Subscribe**。 -- **Topic**: このルールに対応するトピックを設定。 +- **Permission**: 現在のクライアント/ユーザーからの特定の操作リクエストを許可するか拒否するか。オプション値：**Allow**、**Deny**。 +- **Action**: このルールに対応する操作を設定します。オプション値：**Publish**、**Subscribe**、**Publish & Subscribe**。 +- **Topic**: このルールに対応するトピックを設定します。 EMQX は単一のクライアントまたはユーザーに対して複数の認可チェックルールを設定可能で、ページ上の **Move Up** と **Move Down** ボタンで異なるルールの実行順序や優先度を調整できます。 -複数のクライアントやユーザーに対して同時に認可チェックルールを設定したい場合は、HTTP API を通じて関連設定をインポートできます。 +複数のクライアントやユーザーに対して一括で認可チェックルールを設定したい場合は、HTTP API を通じて関連設定をインポートできます。 ### API での作成 ルールは `/api/v5/authorization/sources/built_in_database` API で管理します。 -各ルールは以下に適用されます： -* clientid で識別される特定のクライアント - * `/api/v5/authorization/sources/built_in_database/clientid` -* username で識別される特定のクライアント - * `/api/v5/authorization/sources/built_in_database/username` -* 全クライアント - * `/api/v5/authorization/sources/built_in_database/all` +Built-in Database バックエンドの認可ルールを API で管理するには、以下の手順に従います。 -以下はクライアント (`client1`) に対するルール作成の簡単な例です： +#### ステップ 1: 認証トークンの取得 + +EMQX Dashboard に認証して API アクセス用のトークンを取得します。 + +```bash +export EMQX_TOKEN=$(curl --silent -X 'POST' "http://localhost:18083/api/v5/login" \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{"username": "admin","password": "public"}' | jq -r ".token") +``` + +#### ステップ 2: 組み込みデータベース認可ソースの作成 ```bash curl -X 'POST' \ - 'http://localhost:18083/api/v5/authorization/sources/built_in_database/clientid' \ - -H 'accept: */*' \ + 'http://localhost:18083/api/v5/authorization/sources' \ + -H "Authorization: Bearer $EMQX_TOKEN" \ + -H 'Accept: */*' \ -H 'Content-Type: application/json' \ - -d '[ - { - "clientid": "client1", + -d '{ + "enable": true, + "max_rules": 100, + "type": "built_in_database" + }' +``` + +#### ステップ 3: 認可ルールの作成 + +以下の対象に対してルールを作成できます。 + +- **クライアント ID による特定クライアント**： + + ```bash + curl -X 'POST' \ + 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/clients' \ + -H "Authorization: Bearer $EMQX_TOKEN" \ + -H 'Accept: */*' \ + -H 'Content-Type: application/json' \ + -d '[ + { + "clientid": "client1", + "rules": [ + { + "action": "publish", + "permission": "allow", + "topic": "test/topic/1" + }, + { + "action": "subscribe", + "permission": "allow", + "topic": "test/topic/2" + }, + { + "action": "all", + "permission": "deny", + "topic": "eq test/#" + } + ] + } + ]' + ``` + +- **ユーザー名による特定ユーザー**： + + ```bash + curl -X 'POST' \ + 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users' \ + -H "Authorization: Bearer $EMQX_TOKEN" \ + -H 'Accept: */*' \ + -H 'Content-Type: application/json' \ + -d '[ + { + "username": "user1", + "rules": [ + { + "action": "publish", + "permission": "allow", + "topic": "test/topic/1" + }, + { + "action": "subscribe", + "permission": "allow", + "topic": "test/topic/2" + }, + { + "action": "all", + "permission": "deny", + "topic": "eq test/#" + } + ] + } + ]' + ``` + +- **全クライアントに対してグローバルに**： + + ```bash + curl -X 'POST' \ + 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/all' \ + -H "Authorization: Bearer $EMQX_TOKEN" \ + -H 'Accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ "rules": [ { "action": "publish", @@ -98,13 +185,13 @@ curl -X 'POST' \ "topic": "eq test/#" } ] - } -]' -``` + }' + ``` + +各ルールには以下を含みます： -各ルールは以下を含みます： -* `permission`: 現在のクライアント／ユーザーからの特定の操作リクエストを許可するか拒否するか。オプション値は `allow` または `deny`。 -* `action`: このルールに対応する操作。オプション値は `publish`、`subscribe`、または `all`。 -* `topic`: このルールに対応するトピック。 [トピックプレースホルダー](./authz.md#topic-placeholders) をサポートします。 -* `qos`: （オプション）ルールが適用される QoS レベルを指定する数値配列。例：`[0, 1]`、`[1, 2]`。デフォルトはすべての QoS レベル。 -* `retain`: （オプション）現在のルールがリテインメッセージをサポートするかどうか。値は `true` または `false`。デフォルトはリテインメッセージを許可。 +- `permission`: 操作を許可するか拒否するか。値は `allow`、`deny`。 +- `action`: 操作タイプ。値は `publish`、`subscribe`、または `all`。 +- `topic`: トピックフィルター。[トピックプレースホルダー](./authz.md#topic-placeholders)をサポート。 +- `qos`: *(オプション)* このルールが適用される QoS レベルの配列。例: `[0, 1]`。指定しない場合はすべての QoS レベルに適用。 +- `retain`: *(オプション)* このルールがリテインメッセージに適用されるかどうか。値は `true`、`false`。指定しない場合はリテインメッセージを許可。 diff --git a/ja_JP/changes/all-changes-ee.md b/ja_JP/changes/all-changes-ee.md index 64090bc97..8c082aa6b 100644 --- a/ja_JP/changes/all-changes-ee.md +++ b/ja_JP/changes/all-changes-ee.md @@ -1,6 +1,6 @@ # EMQX Enterprise リリースノート -EMQX Enterprise のリリースノートページでは、各バージョンに含まれる更新、機能強化、および修正の詳細な記録を提供しています。 +EMQX Enterprise のリリースノートページでは、各バージョンに含まれる更新内容、機能強化、および修正点を網羅的かつ詳細に記録しています。 ## v5.10 @@ -8,10 +8,12 @@ EMQX Enterprise のリリースノートページでは、各バージョンに ## v5.9 +- [5.9.1](./changes-ee-v5.md#_5-9-1): 2025-07-02 - [5.9.0](./changes-ee-v5.md#_5-9-0): 2025-05-02 ## v5.8 +- [5.8.7](./changes-ee-v5.md#_5-8-7): 2025-07-02 - [5.8.6](./changes-ee-v5.md#_5-8-6): 2025-03-25 - [5.8.5](./changes-ee-v5.md#_5-8-5): 2025-02-25 - [5.8.4](./changes-ee-v5.md#_5-8-4): 2024-12-26 diff --git a/ja_JP/changes/breaking-changes-ee-5.9.md b/ja_JP/changes/breaking-changes-ee-5.9.md index 510b8c809..05cd9f2e0 100644 --- a/ja_JP/changes/breaking-changes-ee-5.9.md +++ b/ja_JP/changes/breaking-changes-ee-5.9.md @@ -1,9 +1,13 @@ -# Incompatible Changes in EMQX 5.9 +# EMQX 5.9 における非互換変更点 + +## 5.9.1 + +- [#15156](https://github.com/emqx/emqx/pull/15156) `dashboard.sso.oidc.issuer` フィールドに対して厳密なスキーマバリデーションを追加しました。このフィールドには有効なURLを指定する必要があります。以前は無効な設定でもAPIがエラーを返さず受け入れてしまい、EMQXの再起動に失敗してクラッシュ（`erl_crash.dump`）を引き起こす可能性がありました。 ## 5.9.0 -- [#14865](https://github.com/emqx/emqx/pull/14865) Dropped old LDAP authentication config layout (deprecated since v5.4). - Move `password_attribute` and `is_superuser_attribute` under the `method` block: +- [#14865](https://github.com/emqx/emqx/pull/14865) 古いLDAP認証設定レイアウト（v5.4以降非推奨）を廃止しました。 + `password_attribute` と `is_superuser_attribute` は `method` ブロック内に移動してください： ```hcl method { type = hash @@ -12,20 +16,21 @@ } ``` -- [#14765](https://github.com/emqx/emqx/pull/14765) Added extra validation for using Named Instances in SQL Server Connector. Previously, we could not infer when the user furnished an explicit port for SQL Server, and always added the default port if not explicitly defined. +- [#14765](https://github.com/emqx/emqx/pull/14765) SQL ServerコネクターにおけるNamed Instances使用時の追加バリデーションを実装しました。 + 以前はユーザーが明示的にポートを指定したかどうかを判別できず、明示的に指定されていない場合は常にデフォルトポートを付加していました。 - For Named Instances, we need to explicitly define a port to connect to when connecting with the ODBC driver. And the driver happily connects to whatever instance is running on that port, completely ignoring the given Instance Name, if any. + Named Instancesの場合、ODBCドライバーで接続する際にポートを明示的に指定する必要があります。ドライバーは指定されたインスタンス名を無視し、そのポートで稼働しているインスタンスに接続します。 - Now, we impose that the port is to be explicitly defined when an instance name is given, and we also attempt to infer differences between desired and connected instance names during health checks. + 今後はインスタンス名が指定された場合にポートを明示的に定義することを必須とし、ヘルスチェック時に希望するインスタンス名と接続先インスタンス名の違いを推測する処理も追加しました。 -- [#14773](https://github.com/emqx/emqx/pull/14773) Rate limiting configuration options have been changed. - - This change is incompatible with versions prior to 5.1.0 - - This change is also incompatible with manually modified limiter configurations that use structures from versions prior to 5.1.0 - - The undocumented endpoint `/configs/limiter` has been removed - -- [#14703](https://github.com/emqx/emqx/pull/14703) Changed the maximum allowed value for `force_shutdown.max_heap_size` to `128GB`. +- [#14773](https://github.com/emqx/emqx/pull/14773) レート制限設定オプションを変更しました。 + - この変更は5.1.0より前のバージョンとは非互換です。 + - 5.1.0より前のバージョンの構造を利用した手動変更済みのリミッター設定とも非互換です。 + - 非公開エンドポイント `/configs/limiter` は削除されました。 -- [#14957](https://github.com/emqx/emqx/pull/14957) The way plugin configurations are updated has changed. The system now respects the result of the `on_config_changed` callback when updating a plugin's configuration. This change only affects new configuration updates made through the Dashboard. The result of the `on_config_changed` callback is still ignored for configurations that have already been stored in the cluster. +- [#14703](https://github.com/emqx/emqx/pull/14703) `force_shutdown.max_heap_size` の最大許容値を `128GB` に変更しました。 - Additionally, plugin apps are now loaded during plugin installation to ensure the `on_config_changed` callback is called even for stopped plugins. +- [#14957](https://github.com/emqx/emqx/pull/14957) プラグイン設定の更新方法を変更しました。 + システムはプラグイン設定更新時に `on_config_changed` コールバックの結果を尊重するようになりました。この変更はDashboard経由の新規設定更新にのみ影響し、クラスタに既に保存されている設定については引き続きコールバック結果を無視します。 + さらに、プラグインのインストール時にプラグインアプリをロードするようにし、停止中のプラグインに対しても `on_config_changed` コールバックが呼ばれるようにしました。 diff --git a/ja_JP/changes/changes-ee-v5.md b/ja_JP/changes/changes-ee-v5.md index a33943d4f..32d170924 100644 --- a/ja_JP/changes/changes-ee-v5.md +++ b/ja_JP/changes/changes-ee-v5.md @@ -202,6 +202,78 @@ Make sure to check the breaking changes and known issues before upgrading to EMQ - [#15216](https://github.com/emqx/emqx/pull/15216) Fixed a crash of `emqx_telemetry` process when there are plugins activated. +## 5.9.1 + +*Release Date: 2025-07-02* + +Make sure to check the breaking changes and known issues before upgrading to EMQX 5.9.1. + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +- [#15160](https://github.com/emqx/emqx/pull/15160) Added the `DELETE /mt/bulk_delete_ns` API for multi-tenancy management, which allows deleting namespaces in bulk. + +- [#15158](https://github.com/emqx/emqx/pull/15158) Added new `emqx ctl conf remove x.y.z` command, which removes the configuration key path `x.y.z` from the existing configuration. + +- [#15157](https://github.com/emqx/emqx/pull/15157) Added support for specifying private key file path for Snowflake Connector instead of using password. + + Users should either use password, private key, or neither (set parameters in `/etc/odbc.ini`). + +- [#15043](https://github.com/emqx/emqx/pull/15043) Instrument the DS Raft backend with basic metrics to provide insights into cluster status, database overview, shard replication, and replica transitions. + +### Bug Fixes + +#### Data Integration + +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. + Now the system's current millisecond value is used instead, and millisecond precision is enforced. + +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. + +- [#15154](https://github.com/emqx/emqx/pull/15154) Fixed a rare race condition in Actions running in aggregated mode (e.g., S3, Azure Blob Storage, Snowflake) that could lead to a crash with errors like: + + ``` + ** Reason for termination == + ** {function_clause,[{emqx_connector_aggregator,handle_close_buffer,[...], ... + ``` + +- [#15147](https://github.com/emqx/emqx/pull/15147) Fixed an issue where some Actions failed to emit trace events during rule testing with simulated input data, even after request rendering. + + Affected Actions: + + - Couchbase + - Snowflake + - IoTDB (Thrift driver) + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. + +#### Smart Data Hub + +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#15190](https://github.com/emqx/emqx/pull/15190) Enhanced Message Transformation by allowing hard-coded values for QoS and topic. + +#### Observability + +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + +#### Telemetry + +- [#15216](https://github.com/emqx/emqx/pull/15216) Fixed a crash in the `emqx_telemetry` process that could occur when plugins were activated. + +#### Access Control + +- [#15184](https://github.com/emqx/emqx/pull/15184) Fixed the formatting of error messages returned when creating a blacklist fails. + +#### Clustering + +- [#15180](https://github.com/emqx/emqx/pull/15180) Reduced the risk of deadlocks during channel registration by fixing improper handling of `badrpc` errors in the `ekka_locker` module. These errors previously led to false positives in lock operations, potentially causing inconsistent cluster state and deadlocks. + +#### Security + + +- [#15159](https://github.com/emqx/emqx/pull/15159) Improved handling of Certificate Revocation List (CRL) Distribution Point URLs by stopping their refresh after repeated failures (default: 60 seconds). This prevents excessive error logs from unreachable URLs and improves overall system stability. + ## 5.9.0 *Release Date: 2025-05-02* @@ -636,6 +708,41 @@ Make sure to check the breaking changes and known issues before upgrading to EMQ - [#14775](https://github.com/emqx/emqx/pull/14775) QUIC Listener: Fixed issue where zone configurations are not applied after a config reload. +## 5.8.7 + +*Release Date: 2025-07-02* + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +### Bug Fixes + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. Now the system's current millisecond value is used instead, and millisecond precision is enforced. +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#14989](https://github.com/emqx/emqx/pull/14989) Optimized the Kinesis Connector and Action to significantly reduce the number of AWS API calls during startup and health checks. This change helps prevent exceeding AWS Kinesis API rate limits (e.g., `ListStreams` and `DescribeStream`), which previously led to frequent health check failures when using larger connection pools or multiple connectors. +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + +## 5.8.7 + +*Release Date: 2025-07-02* + +### Enhancements + +- [#15364](https://github.com/emqx/emqx/pull/15364) Added support for custom HTTP headers in the OpenTelemetry gRPC (over HTTP/2) integration. This enhancement enables compatibility with collectors that require HTTP authentication. + +### Bug Fixes + +- [#15383](https://github.com/emqx/emqx/pull/15383) Fixed a potential resource leak in the MQTT bridge. When the bridge failed to start, the topic index table was not properly cleaned up. This fix ensures that the index table is correctly deleted to prevent resource leaks. +- [#15331](https://github.com/emqx/emqx/pull/15331) Fixed an issue in the InfluxDB action where line protocol conversion failed if the `timestamp` in `WriteSyntax` was left blank and no timestamp field was provided in the rule. + Now the system's current millisecond value is used instead, and millisecond precision is enforced. +- [#15274](https://github.com/emqx/emqx/pull/15274) Improved the resilience of Postgres, Matrix, and TimescaleDB connectors by triggering a full reconnection on any health check failure. Previously, failed health checks could leave the connection in a broken state, causing operations to hang and potentially leading to out-of-memory issues. +- [#15224](https://github.com/emqx/emqx/pull/15224) Fixed an issue where updating an External Schema Registry via the Dashboard would unintentionally overwrite the existing password with `******`. The password is now correctly preserved during updates. +- [#14989](https://github.com/emqx/emqx/pull/14989) Optimized the Kinesis Connector and Action to significantly reduce the number of AWS API calls during startup and health checks. This change helps prevent exceeding AWS Kinesis API rate limits (e.g., `ListStreams` and `DescribeStream`), which previously led to frequent health check failures when using larger connection pools or multiple connectors. +- [#15299](https://github.com/emqx/emqx/pull/15299) Fixed a `badarg` error that occurred when exporting OpenTelemetry metrics. + ## 5.8.6 *Release Date: 2025-03-25* diff --git a/ja_JP/dashboard/introduction.md b/ja_JP/dashboard/introduction.md index 191bbb194..f01daf8e5 100644 --- a/ja_JP/dashboard/introduction.md +++ b/ja_JP/dashboard/introduction.md @@ -1,26 +1,26 @@ -# EMQX Dashboard +# EMQX ダッシュボード -EMQXは、EMQXクラスターの監視および管理を行い、必要な機能をウェブページ経由で設定できる組み込みのDashboard管理コンソールを提供します。新しいDashboardは刷新されたデザインを採用し、使いやすいMQTTブローカー管理UIを提供します。 +EMQX は、EMQX クラスターの監視および管理を行い、必要な機能をウェブページ経由で設定できる組み込みのダッシュボード管理コンソールを提供しています。新しいダッシュボードは刷新されたデザインを採用し、使いやすい MQTT ブローカー管理 UI を提供します。 -EMQX Dashboardの新しいUI/UXデザインは、主要なデータやメトリクスの表示と内容を最適化し、視覚的な体験を向上させるとともに、接続、サブスクライブ、パブリッシュの認証・認可管理、データブリッジやルールエンジンを用いたデータ統合変換のサポートなど、より包括的で強力かつ使いやすい組み込み機能を提供します。ブラウザからの迅速かつ簡単なアクセスにより、ユーザーはより便利にEMQXを利用してIoTビジネスの開発を進められます。 +EMQX ダッシュボードの新しい UI/UX デザインは、主要なデータやメトリクスの表示と内容を最適化し、視覚的な体験を向上させるとともに、接続、サブスクライブ、パブリッシュの認証および認可管理、データブリッジングやルールエンジンを用いたデータ統合変換のサポートなど、より包括的で強力かつ使いやすい組み込み機能を提供します。ブラウザからの迅速かつ簡単なアクセスにより、ユーザーはより便利に EMQX を利用して IoT ビジネスの開発を進められます。 ![image](./assets/dashboard_preview.png) ## 主な機能 -このセクションでは、Dashboardを通じて設定および管理可能なEMQXの各種機能を紹介します。 +このセクションでは、ダッシュボードを通じて設定および管理できる EMQX のさまざまな機能を紹介します。 -### [モニタリング](./monitoring.md) +### [監視](./monitoring.md) -稼働中のEMQXクラスターの全体情報を表示します。接続数、サブスクライブされたトピック、メッセージ配信数、インバウンド／アウトバウンドレートなどを含みます。また、ノード一覧、ノード情報、各種システムメトリクス情報も確認可能です。さらに、クライアント接続やサブスクリプションデータの閲覧・管理も行えます。 +稼働中の EMQX クラスターの全体情報を表示します。接続数、サブスクライブされたトピック、メッセージ配信数、インバウンドレート、アウトバウンドレートなどが含まれます。また、ノード一覧、ノード情報、各種システムメトリクス情報も表示可能です。さらに、クライアント接続およびサブスクリプションデータの閲覧・管理も行えます。 ### [アクセス制御](./acloverview.md) -EMQXの認証および認可機構を視覚的に追加・設定できます。 +EMQX の認証および認可機構を視覚的に追加・設定できます。 ### [統合](./bridgeoverview.md) -強力なSQLベースのルールエンジンやデータ統合機能、またはFlowエディターのビジュアル機能を活用し、ローコードでのデータ処理と統合を実現します。これにより、MQTTデータのリアルタイム抽出、フィルタリング、強化、変換、保存、検証が可能です。 +強力な SQL ベースのルールエンジンおよびデータ統合機能、または Flowデザイナーのビジュアル機能を活用して、ローコードでのデータ処理および統合を実現します。これにより、MQTT データのリアルタイム抽出、フィルタリング、拡充、変換、保存、検証が可能です。 ### 管理 @@ -28,49 +28,88 @@ EMQXの認証および認可機構を視覚的に追加・設定できます。 MQTT、ログ、リスナーなどの設定項目をオンラインで変更・更新でき、更新成功後は即時反映されます。 -#### 高度なMQTT設定 +#### 高度な MQTT -トピック書き換え、自動サブスクライブ、遅延パブリッシュ、ファイル転送機能の管理と設定が可能です。 +トピックの書き換え、自動サブスクライブ、遅延パブリッシュ、ファイル転送機能の管理および設定を行います。 #### 拡張機能 -カスタムプラグインの統合により、組み込みのゲートウェイ管理・設定を通じて接続プロトコルを拡張できます。また、Hooksを利用して関数呼び出しやメッセージ、モジュール間のイベント伝達をインターセプトし、システム機能を修正・拡張できます。 +カスタムプラグインの統合により、組み込みのゲートウェイ管理と設定を通じて接続プロトコルを拡張できます。また、Hooks を利用して関数呼び出し、メッセージパス、モジュール間のイベントパスをインターセプトし、システム機能の変更や拡張も可能です。 -### 問題分析と診断 +### 問題解析と診断 -オンラインのMQTT over WebSocketクライアント接続やトピックメトリクスによるデバッグに加え、スロウサブスクリプションやログトレースなどの機能を用いた診断や問題発見もサポートしています。 +オンライン MQTT over WebSocket クライアント接続やトピックメトリクスによるデバッグに加え、スローサブスクリプションやログトレースなどの機能を使った診断や問題発見もサポートしています。 ### システム -ユーザーアカウント、監査ログ、APIキー、ライセンス設定、シングルサインオン機能の管理と設定が可能です。 +ユーザーアカウント、監査ログ、API キー、ライセンス設定、シングルサインオン機能の管理および設定を行います。 -## Dashboardの起動 +## ダッシュボードの起動 -EMQX Dashboardはウェブアプリケーションで、デフォルトでポート`18083`をリッスンします。EMQXを正常にインストール後、ブラウザで （非ローカル環境の場合はlocalhostを実際のIPアドレスに置き換えてください）にアクセスすることでDashboardを利用できます。 +EMQX ダッシュボードはウェブアプリケーションで、デフォルトでポート `18083` をリッスンしています。EMQX を正常にインストールした後、ブラウザで （ローカル以外のマシンにデプロイしている場合は localhost を実際の IP アドレスに置き換えてください）にアクセスすることで、EMQX ダッシュボードを利用できます。 ::: tip -Dashboardを有効にしなくてもEMQXは通常通り利用可能です。Dashboardはユーザーが視覚的に操作するためのオプション機能です。 +EMQX はダッシュボードを有効にしなくても通常通り使用可能です。ダッシュボードはユーザーが視覚的に利用するためのオプションを提供するものです。 ::: ### 初回ログイン -EMQXを初めてインストールしたユーザーは、Dashboardをブラウザで開いた後、デフォルトのユーザー名`admin`とパスワード`public`でログインできます。 +EMQX を初めてインストールしたユーザーは、ブラウザでダッシュボードを開いた後、デフォルトのユーザー名 `admin` とデフォルトパスワード `public` を使ってログインできます。 -初回ログイン時、システムはデフォルトのユーザー名とパスワードでのログインを検出し、セキュリティ確保のためパスワードの変更を強制します。変更後のパスワードは元のパスワードと同一にできず、`public`の再利用は推奨されません。 +初回ログイン時に、システムはデフォルトのユーザー名とパスワードでログインしていることを自動検出し、ダッシュボードへのアクセスセキュリティ向上のためにパスワードの変更を強制します。変更後のパスワードは元のパスワードと同じにできず、再度 `public` を使用することは推奨されません。 -### パスワードのリセット +### URL 経由のトークンベースログイン -Dashboardのログインパスワードは`admins`コマンドでリセット可能です。詳細は[CLI - admins](../admin/cli.md#admins)をご覧ください。 +EMQX 5.6.0 以降、ダッシュボードはトークンベースのログイン方式をサポートしており、認証情報を URL に埋め込むことでユーザーが直接ログインできます。 + +この機能は、ユーザーが手動で認証情報を入力せずに自動的にログインすべきシームレスなリダイレクトや統合シナリオに特に有用です。 + +#### このログイン方法の使い方 + +1. `/login` エンドポイントを使って認証トークンを取得します。レスポンスにはユーザー名が含まれないため、完全な JSON ペイロードをエンコードする前に手動でユーザー名を追加する必要があります。 + + トークンのリクエスト、ユーザー名の挿入、Base64 エンコードを一つのコマンドで実行する例は以下の通りです。 + + ``` + curl -s -X POST "http://127.0.0.1:18083/api/v5/login" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{"username": "admin","password": "public"}' | jq '.username = "admin"' | base64 + ``` + +2. ログイン URL を作成します。エンコードした文字列をダッシュボード URL の `login_meta` クエリパラメータに埋め込みます。 + + EMQX バージョン **5.6.0 未満** の場合： + + ```bash + http://localhost:18083?login_meta=BASE64_ENCODED_STRING + ``` + + これによりデフォルトのクラスター概要ページにリダイレクトされます。 + + EMQX **5.6.0 以降** の場合： + + ```bash + http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING + ``` + + これによりログイン後の遷移先ページを指定できます。 + +この方法により、事前認証済みのスムーズなユーザー体験で EMQX ダッシュボードにアクセス可能です。トークンは安全に取り扱い、適切な有効期限やスコープ制限を設けてください。 + +### パスワードリセット + +ダッシュボードのログインパスワードは `admins` コマンドでリセットできます。詳細は [CLI - admins](../admin/cli.md#admins) を参照してください。 ```bash ./bin/emqx ctl admins passwd ``` -### パスワードの有効期限 +### パスワード有効期限 -現在のDashboardログインパスワードの使用期間が設定された有効期限（`password_expired_time`）を超えると、ログイン時にパスワード更新を促されます。`password_expired_time`設定の詳細は[Dashboard設定](../configuration/dashboard.md)を参照してください。 +現在のダッシュボードログインパスワードの使用期間が設定されたパスワード有効期限（`password_expired_time`）を超えると、ログイン時にパスワード更新を促されます。`password_expired_time` 設定の詳細は [ダッシュボード設定](../configuration/dashboard.md) を参照してください。 -「管理者」ロールのユーザーは[REST API](../admin/api.md)を使ってパスワード有効期限を設定することも可能です。 +「管理者」ロールのユーザーは、[REST API](../admin/api.md) を使ってパスワード有効期限を設定可能です。 **例**: @@ -86,12 +125,12 @@ curl -X 'PUT' \ ### アカウントロックと解除 -セキュリティ強化のため、EMQX Dashboardは「アカウントロックと解除」機能を実装しています。ユーザーが5分間に5回パスワードを誤入力すると、そのアカウントは10分間ロックされます。 +セキュリティ強化のため、EMQX ダッシュボードは「アカウントロックと解除」機能を実装しています。ユーザーが5分間に5回パスワードを誤入力すると、アカウントが10分間ロックされます。 -「管理者」ロールのユーザーはCLIからユーザーのパスワードをリセットすることで手動でアカウントを解除できます。10分経過後は自動的にロックが解除され、通常通りログイン可能になります。 +「管理者」ロールのユーザーは CLI を通じてユーザーのパスワードをリセットし、手動でアカウントロックを解除できます。10分経過後は自動的にロックが解除され、ユーザーは通常通りログイン可能になります。 -管理者はバックエンド設定を通じてロック時間やロック発動までの失敗回数も設定可能です。詳細は[Dashboard設定](../configuration/dashboard.md)をご覧ください。 +管理者はロックアウト期間やロックアウトに必要な失敗回数をバックエンド設定で変更できます。設定の詳細は [ダッシュボード設定](../configuration/dashboard.md) を参照してください。 -## Dashboardの設定 +## ダッシュボードの設定 -DashboardはデフォルトでHTTPをリッスンし、ポート番号は18083です。ユーザーはHTTPSを有効化したり、リスナーポートを変更したりできます。Dashboard設定の詳細な変更方法については、[EMQX Enterprise設定マニュアル](https://docs.emqx.com/en/enterprise/v@EE_VERSION@/hocon/)を参照してください。 +ダッシュボードはデフォルトで HTTP をリッスンし、ポート番号は 18083 です。ユーザーは HTTPS を有効化したり、リスナーポートを変更したりできます。ダッシュボード設定の詳細な変更方法については、[EMQX Enterprise 設定マニュアル](https://docs.emqx.com/en/enterprise/v@EE_VERSION@/hocon/) を参照してください。 diff --git a/ja_JP/data-integration/data-bridge-rocketmq.md b/ja_JP/data-integration/data-bridge-rocketmq.md index 2cc7db057..50685a3ad 100644 --- a/ja_JP/data-integration/data-bridge-rocketmq.md +++ b/ja_JP/data-integration/data-bridge-rocketmq.md @@ -1,48 +1,48 @@ # Bridge MQTT Data into RocketMQ -EMQXは[RocketMQ](https://rocketmq.apache.org/)へのデータブリッジをサポートしており、MQTTメッセージやクライアントイベントをRocketMQに転送できます。例えば、RocketMQを使ってデバイスからのセンサーデータやログデータを収集することが可能です。 +EMQXは[RocketMQ](https://rocketmq.apache.org/)へのデータブリッジをサポートしており、MQTTメッセージやクライアントイベントをRocketMQに転送できます。例えば、RocketMQを利用してデバイスからのセンサーデータやログデータを収集することが可能です。 -本ページでは、EMQXとRocketMQ間のデータ連携の詳細な概要と、データ連携の作成および検証に関する実践的な手順を提供します。 +本ページでは、EMQXとRocketMQ間のデータ統合について詳細に解説し、データ統合の作成および検証方法を実践的に説明します。 ::: tip 注意 -Alibaba CloudがホストするRocketMQサービスを利用する場合、このデータ連携はバッチモードをサポートしていません。 +Alibaba Cloudが提供するRocketMQサービスを利用する場合、本データ統合はバッチモードをサポートしていません。 ::: -## 動作原理 +## 動作概要 -RocketMQデータ連携は、EMQXに標準搭載された機能であり、EMQXのリアルタイムデータキャプチャと送信機能をRocketMQの強力なメッセージキュー処理機能と組み合わせています。組み込みの[ルールエンジン](./rules.md)コンポーネントにより、EMQXからRocketMQへのデータ取り込みが簡素化され、複雑なコーディングが不要になります。 +RocketMQデータ統合は、EMQXに標準搭載された機能であり、EMQXのリアルタイムデータキャプチャおよび送信機能とRocketMQの強力なメッセージキュー処理機能を組み合わせています。組み込みの[ルールエンジン](./rules.md)コンポーネントにより、EMQXからRocketMQへのデータ取り込みが簡素化され、複雑なコーディングを不要にします。 -以下の図は、EMQXとRocketMQ間の典型的なデータ連携アーキテクチャを示しています。 +以下の図は、EMQXとRocketMQ間の典型的なデータ統合アーキテクチャを示しています。 ![EMQX Integration RocketMQ](./assets/emqx-integration-rocketmq.png) -MQTTデータをRocketMQに取り込む流れは次の通りです： +MQTTデータをRocketMQに取り込む流れは以下の通りです： -1. **メッセージのパブリッシュと受信**：産業用IoTデバイスはMQTTプロトコルを通じてEMQXに正常に接続し、リアルタイムMQTTデータをEMQXにパブリッシュします。EMQXがこれらのメッセージを受信すると、ルールエンジン内でマッチング処理を開始します。 -2. **メッセージデータの処理**：メッセージが到着するとルールエンジンを通過し、EMQXで定義されたルールによって処理されます。ルールは事前定義された条件に基づき、RocketMQにルーティングすべきメッセージを判別します。ペイロードの変換が指定されている場合は、データ形式の変換、特定情報のフィルタリング、追加コンテキストによるペイロードの強化などが適用されます。 -3. **RocketMQへのデータ取り込み**：ルールによる処理が完了したメッセージは、RocketMQへの転送アクションがトリガーされます。処理済みデータはシームレスにRocketMQに書き込まれます。 -4. **データの保存と活用**：データがRocketMQに保存された後、企業はそのクエリ機能を活用して様々なユースケースに対応できます。例えば金融業界では、RocketMQを信頼性の高い高性能メッセージキューとして利用し、決済端末や取引システムからのデータを管理します。これにより、リスク管理、不正検知・防止、規制遵守などの要件を満たすためのデータ分析や規制プラットフォームと連携可能です。 +1. **メッセージのパブリッシュと受信**：産業用IoTデバイスはMQTTプロトコルを介してEMQXに正常に接続し、リアルタイムのMQTTデータをEMQXにパブリッシュします。EMQXがメッセージを受信すると、ルールエンジン内でマッチング処理を開始します。 +2. **メッセージデータの処理**：メッセージが到着するとルールエンジンを通過し、EMQXで定義されたルールにより処理されます。ルールは事前に定義された条件に基づき、RocketMQにルーティングすべきメッセージを判定します。ペイロード変換が指定されている場合は、データ形式の変換、特定情報のフィルタリング、追加コンテキストによるペイロードの強化などが適用されます。 +3. **RocketMQへのデータ取り込み**：ルールによる処理が完了すると、メッセージをRocketMQに転送するアクションがトリガーされます。処理済みデータはシームレスにRocketMQに書き込まれます。 +4. **データの保存と活用**：データがRocketMQに保存された後、企業はそのクエリ機能を活用して様々なユースケースに対応できます。例えば金融業界では、RocketMQを信頼性の高い高性能メッセージキューとして利用し、決済端末や取引システムからのデータを管理します。メッセージをデータ分析や規制プラットフォームに連携させ、リスク管理、不正検知防止、法令遵守などの要件を満たします。 -## 特長と利点 +## 特長とメリット -RocketMQとのデータ連携は、以下の特長と利点をビジネスにもたらします： +RocketMQとのデータ統合は、以下の特長と利点をビジネスにもたらします： - **信頼性の高いIoTデータメッセージ配信**：EMQXはMQTTメッセージを信頼性高くバッチ送信でき、IoTデバイスとRocketMQおよびアプリケーションシステムの統合を実現します。 -- **MQTTメッセージの変換**：ルールエンジンを活用し、EMQXはMQTTメッセージの抽出、フィルタリング、強化、変換を行い、RocketMQに送信します。 -- **クラウドネイティブな弾力的スケーリング**：EMQXとRocketMQは共にクラウドネイティブアーキテクチャで構築されており、Kubernetes（K8s）をはじめとしたクラウドネイティブエコシステムとの親和性が高く、ビジネスの急速な成長に対応する無限の弾力的スケールが可能です。 -- **柔軟なトピックマッピング**：RocketMQデータ連携はMQTTトピックとRocketMQトピックの柔軟なマッピングをサポートし、RocketMQメッセージ内のキー（Key）や値（Value）の設定を簡単に行えます。 -- **高スループットシナリオでの処理能力**：RocketMQデータ連携は同期・非同期の両書き込みモードをサポートし、シナリオに応じてレイテンシとスループットのバランスを柔軟に調整可能です。 +- **MQTTメッセージの変換**：ルールエンジンを活用し、EMQXはMQTTメッセージの抽出、フィルタリング、強化、変換を行い、RocketMQ送信前にデータを最適化します。 +- **クラウドネイティブな弾力的スケーリング**：EMQXとRocketMQは共にクラウドネイティブアーキテクチャ上に構築されており、Kubernetes（K8s）に対応し、クラウドネイティブエコシステムと統合可能です。ビジネスの急速な成長に合わせて無限かつ弾力的にスケールアウトできます。 +- **柔軟なトピックマッピング**：RocketMQデータ統合はMQTTトピックとRocketMQトピックの柔軟なマッピングをサポートし、RocketMQメッセージ内のキー（Key）や値（Value）の設定を簡単に行えます。 +- **高スループットシナリオでの処理能力**：RocketMQデータ統合は同期・非同期の両書き込みモードをサポートし、用途に応じてレイテンシとスループットのバランスを柔軟に調整可能です。 ## はじめる前に -このセクションでは、RocketMQデータ連携を作成する前に必要な準備とRocketMQサーバーのセットアップ方法を説明します。 +本節では、RocketMQデータ統合の作成を開始する前に必要な準備、特にRocketMQサーバーのセットアップ方法について説明します。 ### 前提条件 -- EMQXデータ連携の[ルール](./rules.md)に関する知識 -- [データ連携](./data-bridges.md)に関する知識 +- EMQXデータ統合の[ルール](./rules.md)に関する知識 +- [データ統合](./data-bridges.md)に関する知識 ### RocketMQのインストール @@ -81,7 +81,7 @@ services: - mqnamesrv ``` -2. RocketMQの実行に必要なフォルダと設定を作成します。 +2. RocketMQの実行に必要なフォルダと設定を準備します。 ```bash mkdir rocketmq @@ -128,7 +128,6 @@ docker-compose -f rocketmq.yaml up ``` docker run --rm -e NAMESRV_ADDR=host.docker.internal:9876 apache/rocketmq:4.9.4 ./tools.sh org.apache.rocketmq.example.quickstart.Consumer ``` - ::: tip Linux環境では、`host.docker.internal`を実際のIPアドレスに変更してください。 @@ -137,34 +136,34 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し ## コネクターの作成 -このセクションでは、SinkをRocketMQサーバーに接続するためのコネクター作成方法を説明します。 +本節では、SinkをRocketMQサーバーに接続するためのコネクター作成方法を説明します。 -以下の手順は、EMQXとRocketMQをローカルマシンで実行している場合を想定しています。リモートで実行している場合は設定を適宜調整してください。 +以下の手順は、EMQXとRocketMQをローカルマシンで実行している場合を想定しています。リモート環境で実行している場合は設定を適宜調整してください。 1. EMQXダッシュボードに入り、**Integration** -> **Connectors**をクリックします。 2. ページ右上の**Create**をクリックします。 3. **Create Connector**ページで**RocketMQ**を選択し、**Next**をクリックします。 -4. **Configuration**ステップで以下を設定します： - - **Connector name**：コネクター名を入力します。英数字の組み合わせで、例：`my_rocketmq` - - **Servers**：`127.0.0.1:9876`を入力 - - **Namespace**：RocketMQサービスにネームスペースが設定されていなければ空欄のまま。 - - **AccessKey**、**SecretKey**、**Secret Token**：サービス構成に応じて空欄または入力 - - その他はデフォルトのまま -5. 詳細設定（任意）：[Sinkの機能](./data-bridges.md#features-of-sink)を参照 -6. **Create**をクリックする前に、**Test Connectivity**でRocketMQサーバーへの接続確認が可能です。 -7. ページ下部の**Create**ボタンをクリックしてコネクター作成を完了します。ポップアップで**Back to Connector List**か**Create Rule**を選択可能です。ルール作成については、[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)および[イベント記録用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-events-recording)を参照してください。 +4. **Configuration**ステップで以下の情報を設定します： + - **Connector name**：コネクター名を入力します。英数字の組み合わせで、例：`my_rocketmq`。 + - **Servers**：`127.0.0.1:9876`を入力します。 + - **Namespace**：RocketMQサービスにネームスペース設定がない場合は空欄のままにします。 + - **AccessKey**、**SecretKey**、**Secret Token**：RocketMQサービスの設定に応じて空欄のままか適宜入力します。 + - その他はデフォルトのままにします。 +5. 詳細設定（任意）：詳細は[Sinkの特長](./data-bridges.md#features-of-sink)を参照してください。 +6. **Create**をクリックする前に、**Test Connectivity**をクリックしてコネクターがRocketMQサーバーに接続できるか確認できます。 +7. ページ下部の**Create**ボタンをクリックしてコネクター作成を完了します。ポップアップで**Back to Connector List**をクリックするか、**Create Rule**をクリックしてSinkを使ったルール作成に進めます。詳細は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)および[イベント記録用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-events-recording)を参照してください。 ## メッセージ保存用RocketMQ Sinkのルール作成 -このセクションでは、ダッシュボードでソースMQTTトピック`t/#`のメッセージを処理し、処理済みデータを設定済みのSink経由でRocketMQトピック`TopicTest`に転送するルールの作成方法を説明します。 +本節では、ソースMQTTトピック`t/#`からのメッセージを処理し、処理済みデータを設定済みSink経由でRocketMQトピック`TopicTest`に転送するルールをダッシュボード上で作成する手順を説明します。 1. EMQXダッシュボードで**Integration** -> **Rules**をクリックします。 2. ページ右上の**Create**をクリックします。 -3. ルールIDに`my_rule`を入力します。メッセージ保存用ルールのSQL文は以下の通りです。これはトピック`t/#`配下のMQTTメッセージをRocketMQに保存することを意味します。 +3. ルールIDに`my_rule`を入力し、メッセージ保存用ルールとして以下のSQL文を**SQL Editor**に入力します。これはトピック`t/#`配下のMQTTメッセージをRocketMQに保存することを意味します。 - 注意：独自のSQL文を指定する場合は、Sinkが必要とするすべてのフィールドを`SELECT`句に含めてください。 + 注意：独自のSQL構文を指定する場合は、Sinkが必要とする全てのフィールドを`SELECT`句に含めてください。 ```sql SELECT @@ -175,17 +174,17 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し ::: tip - 初心者の方は**SQL Examples**や**Enable Test**を使ってSQLルールの学習とテストが可能です。 + 初心者の方は**SQL Examples**と**Enable Test**を利用してSQLルールの学習とテストが可能です。 ::: -4. + **Add Action**ボタンをクリックし、ルールでトリガーされるアクションを定義します。このアクションによりEMQXはルールで処理したデータをRocketMQに送信します。 +4. + **Add Action**ボタンをクリックし、ルールでトリガーされるアクションを定義します。このアクションにより、EMQXはルールで処理したデータをRocketMQに送信します。 -5. **Type of Action**ドロップダウンから`RocketMQ`を選択します。**Action**はデフォルトの`Create Action`のままにします。既存のSinkがあれば選択可能ですが、ここでは新規Sinkを作成します。 +5. **Type of Action**ドロップダウンから`RocketMQ`を選択します。**Action**はデフォルトの`Create Action`のままにします。既存のSinkを選択することも可能ですが、本例では新規Sinkを作成します。 -6. Sinkの名前を入力します。英数字の組み合わせで指定してください。 +6. Sink名を入力します。英数字の組み合わせで指定してください。 -7. **Connector**ドロップダウンから先に作成した`my_rocketmq`を選択します。新規コネクターはドロップダウン横のボタンで作成可能です。設定パラメータは[コネクターの作成](#create-a-connector)を参照してください。 +7. **Connector**ドロップダウンから先に作成した`my_rocketmq`を選択します。新規コネクターを作成する場合はドロップダウン横のボタンをクリックします。設定パラメータの詳細は[コネクターの作成](#create-a-connector)を参照してください。 8. **RocketMQ Topic**欄に`TopicTest`を入力します。 @@ -193,31 +192,31 @@ Linux環境では、`host.docker.internal`を実際のIPアドレスに変更し ::: tip - 空欄の場合、メッセージ全体がRocketMQに転送されます。実際にはJSONテンプレートデータです。 + ここを空欄にするとメッセージ全体がRocketMQに転送されます。実際にはJSONテンプレートデータです。 ::: -10. **Fallback Actions（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[Fallback Actions](./data-bridges.md#fallback-actions)を参照してください。 +10. **フォールバックアクション（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[フォールバックアクション](./data-bridges.md#fallback-actions)を参照してください。 -11. **詳細設定（任意）**：[Sinkの機能](./data-bridges.md#features-of-sink)を参照してください。 +11. 詳細設定（任意）：詳細は[Sinkの特長](./data-bridges.md#features-of-sink)を参照してください。 -12. **Create**をクリックする前に、**Test Connectivity**でSinkがRocketMQサーバーに接続できるか確認できます。 +12. **Create**をクリックする前に**Test Connectivity**を押してSinkがRocketMQサーバーに接続可能か確認できます。 -13. **Create**ボタンをクリックし、Sink設定を完了します。新しいSinkが**Action Outputs**に追加されます。 +13. **Create**ボタンをクリックしてSink設定を完了します。新しいSinkが**Action Outputs**に追加されます。 -14. **Create Rule**ページに戻り、設定内容を確認後、**Create**ボタンをクリックしてルールを生成します。 +14. **Create Rule**ページに戻り、設定内容を確認して**Create**をクリックしルールを生成します。 -これでRocketMQ Sink用のルール作成が完了しました。**Integration** -> **Rules**ページで新規作成したルールを確認できます。**Actions(Sink)**タブをクリックすると新しいRocketMQ Sinkが表示されます。 +これでRocketMQ Sink用のルールが正常に作成されました。**Integration** -> **Rules**ページで新規ルールを確認できます。**Actions(Sink)**タブをクリックすると新しいRocketMQ Sinkが表示されます。 -また、**Integration** -> **Flow Designer**でトポロジーを確認すると、トピック`t/#`配下のメッセージがルール`my_rule`で解析され、RocketMQに送信・保存されていることがわかります。 +また、**Integration** -> **Flow Designer**を開くとトポロジーが表示され、トピック`t/#`配下のメッセージがルール`my_rule`で解析され、RocketMQに送信・保存されていることが確認できます。 ## イベント記録用RocketMQ Sinkのルール作成 -このセクションでは、クライアントのオンライン／オフライン状態を記録し、イベントデータを設定済みSink経由でRocketMQトピック`TestTopic`に転送するルールの作成方法を説明します。 +本節では、クライアントのオンライン／オフライン状態を記録し、イベントデータを設定済みSink経由でRocketMQトピック`TestTopic`に転送するルールの作成方法を説明します。 -ルール作成手順は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)とほぼ同様ですが、SQLルールの文法が異なります。 +ルール作成手順は[メッセージ保存用RocketMQ Sinkのルール作成](#create-a-rule-with-rocketmq-sink-for-message-storage)とほぼ同様ですが、SQLルール構文が異なります。 -オンライン／オフライン状態記録用のSQLルール文は以下の通りです： +オンライン／オフライン状態記録用のSQLルール構文は以下の通りです： ```sql SELECT @@ -228,7 +227,7 @@ FROM ::: tip -便宜上、オンライン／オフラインイベントの受信用に`TopicTest`トピックを再利用します。 +便宜上、オンライン／オフラインイベント受信用に`TopicTest`トピックを再利用します。 ::: @@ -244,7 +243,7 @@ Sinkの稼働状況を確認すると、新規の受信メッセージと送信 データが`TopicTest`トピックに転送されているか確認してください。 -以下のようなデータがコンシューマーに表示されます。 +以下のようなデータがコンシューマーにより出力されます。 ```bash ConsumeMessageThread_please_rename_unique_group_name_4_1 Receive New Messages: [MessageExt [brokerName=broker-a, queueId=3, storeSize=581, queueOffset=0, sysFlag=0, bornTimestamp=1679037578889, bornHost=/172.26.83.106:43920, storeTimestamp=1679037578891, storeHost=/172.26.83.106:10911, msgId=AC1A536A00002A9F000000000000060E, commitLogOffset=1550, bodyCRC=7414108, reconsumeTimes=0, preparedTransactionOffset=0, toString()=Message{topic='TopicTest', flag=0, properties={MIN_OFFSET=0, MAX_OFFSET=8, CONSUME_START_TIME=1679037605342, CLUSTER=DefaultCluster}, body=[...], transactionId='null'}]] diff --git a/ja_JP/data-integration/rule-sql-builtin-functions.md b/ja_JP/data-integration/rule-sql-builtin-functions.md index 49dea3120..6e9be62d7 100644 --- a/ja_JP/data-integration/rule-sql-builtin-functions.md +++ b/ja_JP/data-integration/rule-sql-builtin-functions.md @@ -1,6 +1,6 @@ # 組み込みSQL関数 -ルールエンジンは多様な組み込み関数を提供しています。これらの関数はSQL内で利用でき、基本的なデータ処理を実現します。主なカテゴリは以下の通りです： +ルールエンジンはさまざまな組み込み関数を提供しています。これらの関数はSQL内で利用でき、基本的なデータ処理を実現できます。主なカテゴリは以下の通りです： - [数学関数](#mathematical-functions) - [データ型判定関数](#data-type-judgment-functions) @@ -18,20 +18,20 @@ - [システム関数](#system-function) - [条件関数](#conditional-functions) -本節では、すべての関数宣言は以下の形式に準拠しています： +本節の関数宣言はすべて以下の形式に準拠しています： ```bash FuncName(Arg 1: Type 1 | ..., ...) -> Type 1 | ... ``` -例えば、`abs(X: integer | float) -> integer | float` は、引数 `X` のデータ型が整数または浮動小数点数であり、戻り値の型もそれに対応することを意味します。 +例えば、`abs(X: integer | float) -> integer | float` は、引数 `X` のデータ型が整数または浮動小数点数であり、戻り値も同様に整数または浮動小数点数であることを示します。 -指定された引数が範囲外であったり、サポートされていないデータ型を使用した場合、現在のSQL実行は失敗し、失敗回数が1増加しますのでご注意ください。 +引数が指定範囲を超えたり、サポートされていないデータ型を使用した場合、現在のSQL実行は失敗し、失敗回数が1増加しますのでご注意ください。 :::tip 1. 一部のエスケープシーケンスは使用時にアンエスケープが必要です。詳細は [unescape関数](#unescapestring-string---string) を参照してください。 -2. EMQX 5.0以降、複雑なデータ変換に [jq構文](https://stedolan.github.io/jq/manual/) を利用可能です。詳細は [jq関数](./rule-sql-jq.md) をご覧ください。 +2. EMQX 5.0以降、複雑なデータ変換には [jq構文](https://stedolan.github.io/jq/manual/) を利用可能です。詳細は [jq関数](./rule-sql-jq.md) セクションをご覧ください。 ::: @@ -41,7 +41,7 @@ EMQXは幅広い数学関数をサポートしています： - 三角関数および双曲線関数：sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh - 数値関数：abs, ceil, floor, round, sqrt, fmod -- 指数関数および対数関数：exp, power, log, log10, log2 +- 指数・対数関数：exp, power, log, log10, log2 ### abs(X: integer | float) -> integer | float @@ -126,7 +126,7 @@ cosh(0.5) = 1.1276259652063807 ### exp(X: integer | float) -> float -自然対数の底 `e` の `X` 乗を返します。例： +自然対数の底 e の `X` 乗を返します。例： ```bash exp(1) = 2.718281828459045 @@ -150,7 +150,7 @@ fmod(6.5, 2.5) = 1.5 ### log(X: integer | float) -> float -`X` の自然対数を返します。`X` は0より大きい必要があります。例： +`X` の自然対数を返します。`X` は0より大きくなければなりません。例： ```bash log(7.38905609893065) = 2.0 @@ -158,7 +158,7 @@ log(7.38905609893065) = 2.0 ### log10(X: integer | float) -> float -`X` の底10の対数を返します。`X` は0より大きい必要があります。例： +`X` の常用対数（底10）を返します。`X` は0より大きくなければなりません。例： ```bash log10(100) = 2.0 @@ -166,7 +166,7 @@ log10(100) = 2.0 ### log2(X: integer | float) -> float -`X` の底2の対数を返します。`X` は0より大きい必要があります。例： +`X` の底2の対数を返します。`X` は0より大きくなければなりません。例： ```bash log2(8) = 3.0 @@ -243,7 +243,7 @@ tanh(0.5) = 0.46211715726000974 ### is_array(Term: any) -> boolean -`Term` が配列型か判定します。例： +`Term` が配列型かどうか判定します。例： ```bash is_array([1, 2]) = true @@ -255,7 +255,7 @@ is_array('[1, 2]') = false ### is_bool(Term: any) -> boolean -`Term` がブール型か判定します。例： +`Term` がブール型かどうか判定します。例： ```bash is_bool(true) = true @@ -265,7 +265,7 @@ is_bool('true') = false ### is_float(Term: any) -> boolean -`Term` が浮動小数点型か判定します。例： +`Term` が浮動小数点型かどうか判定します。例： ```bash is_float(123.4) = true @@ -274,7 +274,7 @@ is_float(123) = false ### is_int(Term: any) -> boolean -`Term` が整数型か判定します。例： +`Term` が整数型かどうか判定します。例： ```bash is_int(123) = true @@ -283,7 +283,7 @@ is_int(123.4) = false ### is_map(Term: any) -> boolean -`Term` がマップ型か判定します。例： +`Term` がマップ型かどうか判定します。例： ```bash is_map(json_decode('{"value": 1}')) = true @@ -292,8 +292,8 @@ is_map(json_decode('[{"value": 1}]')) = false ### is_null(Term: any) -> boolean -変数 `Term` が未定義か判定します。 -この関数は変数に値が割り当てられているかを判定するために使い、値がJSONの `null` であっても未定義とはみなしません。 +変数 `Term` が未定義かどうか判定します。 +この関数は変数に値が割り当てられているかを判定し、値がJSONの `null` であっても未定義とはみなしません。 例： @@ -305,7 +305,7 @@ is_null(map_get('b', json_decode('{"b": null}'))) = false ### is_null_var(Term: any) -> boolean -変数 `Term` が未定義または `null` か判定します。例： +変数 `Term` が未定義または `null` かどうか判定します。例： ```sql is_null_var(this_is_an_unassigned_variable) = true @@ -319,7 +319,7 @@ is_null_var(map_get('b', json_decode('{"b": null}'))) = true ### is_num(Term: any) -> boolean -`Term` が整数または浮動小数点型か判定します。例： +`Term` が整数または浮動小数点型かどうか判定します。例： ```bash is_num(123) = true @@ -329,7 +329,7 @@ is_num('123') = false ### is_str(Term: any) -> boolean -`Term` が文字列型か判定します。例： +`Term` が文字列型かどうか判定します。例： ```bash is_str('123') = true @@ -338,7 +338,7 @@ is_str(123) = false ### is_empty(Array or Map) -> boolean -配列またはマップが空か判定します。例： +配列またはマップが空かどうか判定します。例： ```bash is_empty(json_decode('{}')) = true @@ -352,7 +352,7 @@ is_empty(map_get('key', '{"key" : [1}')) = false ### bool(Term: boolean | integer | string) -> boolean -`Term` をブール型に変換します。`Term` はブール型、整数型の0または1、文字列型のtrueまたはfalseのみ許容されます。 +`Term` をブール型に変換します。`Term` はブール型、整数型（0または1）、または文字列型（"true" または "false"）でなければなりません。 例： @@ -362,7 +362,7 @@ bool(true) = true bool(0) = false bool('false') = false -# 誤り例 +# 間違い例 bool(20) bool('True') ``` @@ -371,7 +371,7 @@ bool('True') `Term` を浮動小数点数に変換します。 -`Term` が文字列の場合、科学的記数法が利用可能です（例：`float('3.14e4')`）。浮動小数点数は最大16桁の有効数字をサポートします。文字列で表現された浮動小数点数の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 +`Term` が文字列の場合、指数表記も使用可能です（例：`float('3.14e4')`）。浮動小数点数は最大16桁の有効数字をサポートします。文字列で表現された浮動小数点数の有効数字が16桁を超える場合、丸め誤差が発生することがあります。 例： @@ -400,9 +400,9 @@ float('0.000012345', 5) = 0.00001 ### float2str(Float: float, Decimals: integer) -> string -浮動小数点数 `Float` を文字列に変換します。小数点以下最大 `Decimals` 桁まで含み、末尾のゼロは切り捨てられます。`Decimals` の範囲は `[0, 253]` です。`Float` の有効数字が16桁を超える場合、変換時に丸め誤差が発生する可能性があります。 +浮動小数点数 `Float` を文字列に変換します。小数点以下最大 `Decimals` 桁まで含み、末尾のゼロは切り捨てられます。`Decimals` の範囲は `[0, 253]` です。`Float` の有効数字が16桁を超える場合、変換時に丸め誤差が生じることがあります。 -浮動小数点数はコンピュータ上で正確に保存できないため、`Decimals` が `Float` の小数点以下の桁数（先行ゼロ含む）を超える場合、`float2str` は `Float` の2進近似値の10進表現を返すことがあります。 +浮動小数点数はコンピュータ上で正確に格納できないため、`Decimals` が `Float` の小数点以下の桁数（先行ゼロ含む）より大きい場合、`float2str` は `Float` の2進近似の10進表現を返すことがあります。 例： @@ -442,7 +442,7 @@ int('0010') = 10 int('3.1415e2') = 314 int(substr('Number 100', 7)) = 100 -# 誤り例 +# 間違い例 int('-100+200') int('Number 100') ``` @@ -452,7 +452,7 @@ int('Number 100') 任意の型の `Term` を文字列に変換します。 - `Term` がマップまたは配列の場合、`str` 関数は `Term` をJSONエンコードしようとします。 -- `Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。戻り値の文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 +- `Term` が浮動小数点数の場合、末尾のゼロを切り捨てた対応する文字列を返します。返される文字列は小数点以下最大10桁まで保持します。より多くの小数桁を返すには `float2str` 関数を使用してください。 例： @@ -463,11 +463,12 @@ str(json_decode({"msg": "hello"})) = '{"msg":"hello"}' str(json_decode('[{"msg": "hello"}]')) = '[{"msg":"hello"}]' # 末尾のゼロは切り捨てられます -# 小数点以下最大10桁を保持 +# 小数点以下最大10桁まで保持 str(0.30000000040) = '0.3000000004' str(0.30000000004) = '0.3' # 小数点以下10桁で丸められます +# 10桁目以降で丸め str(3.14159265359) = '3.1415926536' str(0.000000314159265359) = '0.0000003142' ``` @@ -485,11 +486,12 @@ str_utf8(json_decode({"msg": "hello"})) = '{"msg":"hello"}' str_utf8(json_decode('[{"msg": "hello"}]')) = '[{"msg":"hello"}]' # 末尾のゼロは切り捨てられます -# 小数点以下最大10桁を保持 +# 小数点以下最大10桁まで保持 str_utf8(0.30000000040) = '0.3000000004' str_utf8(0.30000000004) = '0.3' # 小数点以下10桁で丸められます +# 10桁目以降で丸め str_utf8(3.14159265359) = '3.1415926536' str_utf8(0.000000314159265359) = '0.0000003142' ``` @@ -501,12 +503,12 @@ str_utf8(0.000000314159265359) = '0.0000003142' ::: tip UTF-16リトルエンディアンエンコード文字列はJSONオブジェクト内で正しく表示されない場合があります。EMQXでは通常バイナリデータとして扱われます。可読な16進文字列に変換するには `bin2hexstr` 関数を使用してください。 -このエンコードはMicrosoft SQL Serverなど、リトルエンディアンUTF-16を利用するシステムで一般的に使用されます。 +このエンコードはMicrosoft SQL Serverなど、リトルエンディアンUTF-16を利用するシステムで一般的に使われます。 ::: ```bash -# Unicodeの 'h' の例: +# Unicodeの `h`: # | h(\u68) | # | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 1 | 0 | 0 | 0 | (ビッグエンディアン) # | 0x00 | 0x68 | @@ -519,11 +521,11 @@ bin2hexstr(str_utf16_le('hello')) = '680065006C006C006F00' ## 文字列操作関数 -文字列の大文字・小文字変換、空白削除、部分文字列抽出、置換、エスケープ・アンエスケープなどに利用できます。 +文字列の大文字・小文字変換、空白除去、部分文字列抽出、置換、エスケープ・アンエスケープなどに使用します。 ### ascii(Char: string) -> integer -文字 `Char` のASCIIコードを返します。`Char` に複数文字が含まれる場合、最初の1文字のコードのみ返します。例： +文字 `Char` のASCIIコードを返します。`Char` に複数文字が含まれる場合は最初の1文字のコードのみ返します。例： ```bash ascii('a') = 97 @@ -540,7 +542,7 @@ concat('Name:', 'John') = 'Name:John' ### find(String: string, SearchPattern: string) -> string -`String` 内で部分文字列 `SearchPattern` を検索し、`SearchPattern` より前の部分を削除して残りを返します。`SearchPattern` が見つからない場合は空文字列を返します。`find(String, SearchPattern, 'leading')` と同等です。 +`String` 内で部分文字列 `SearchPattern` を検索し、`SearchPattern` より前の内容を削除して残りを返します。`SearchPattern` が見つからなければ空文字列を返します。`find(String, SearchPattern)` は `find(String, SearchPattern, 'leading')` と同等です。 例： @@ -551,9 +553,7 @@ find('..., Value: 1.2', 'Data') = '' ### find(String: string, SearchPattern: string, Direction: string) -> string -`find/2` と同様ですが、`Direction` で検索方向を指定できます。 - -例： +`find/2` と同様ですが、`Direction` で検索方向を指定できます。例： ```bash find('Front, Middle, End', ', ', 'leading') = ', Middle, End' @@ -578,7 +578,7 @@ lower('Hello') = 'hello' ### ltrim(String: string) -> string -`trim/1` と同様ですが、文字列の先頭の空白文字のみを削除します。例： +`trim/1` と同様ですが、先頭の空白文字のみ削除します。例： ```bash ltrim('\t hello \n') = 'hello \n' @@ -587,7 +587,7 @@ ltrim('\t hello \r\n') = 'hello \r\n' ### pad(String: string, Length: integer) -> string -`String` の末尾に空白を追加して指定長さ `Length` にパディングします。例： +`String` の末尾に空白を詰めて指定長さ `Length` にします。例： ```bash pad('hello', 8) = 'hello ' @@ -595,9 +595,9 @@ pad('hello', 8) = 'hello ' ### pad(String: string, Length: integer, Direction: string) -> string -`pad/2` と同様ですが、`Direction` でパディング方向を指定できます。 -`leading` は先頭に空白を埋め、`trailing` は末尾に空白を埋め、`both` は両端に空白を埋めます。 -`both` 指定時、埋める空白数が奇数の場合は末尾に多く埋めます。 +`pad/2` と同様ですが、`Direction` で詰める方向を指定できます。`leading` は先頭に空白を詰め、`trailing` は末尾に空白を詰め、`both` は両端に詰めます。 + +`both` 指定時、詰める空白数が奇数の場合は末尾に多く詰めます。 例： @@ -609,9 +609,9 @@ pad('hello', 8, 'both') = ' hello ' ### pad(String: string, Length: integer, Direction: string, Char: string) -> string -`pad/3` と同様ですが、指定したグラフェムクラスタ `Char` でパディングします。 +`pad/3` と同様ですが、指定したグラフェムクラスタ `Char` で詰めます。 -ルールエンジンは `Char` が合法なグラフェムクラスタかをチェックしないため、`Char` が複数文字でも1文字分として扱われます。例： +ルールエンジンは `Char` が合法的なグラフェムクラスタかどうかをチェックしないため、`Char` の文字数に関わらず1文字分として処理されます。例： ```bash pad('hello', 8, 'trailing', '!') = 'hello!!!' @@ -630,7 +630,7 @@ regex_match('a23', '^\d+$') = false ### regex_replace(String: string, Expression: string, Replacement: string) -> string -文字列 `String` の正規表現 `Expression` にマッチする部分を `Replacement` に置換します。マッチがなければ元の文字列を返します。例： +正規表現 `Expression` にマッチした部分を文字列 `Replacement` に置換します。マッチしなければ元の文字列を返します。例： ```bash regex_replace('hello 123', '\d+', 'world') = 'hello world' @@ -641,11 +641,11 @@ regex_replace('a;b; c', ';\s*', ',') = 'a,b,c' ::: tip -この関数はEMQX v5.7.1以降で導入されました。 +EMQX v5.7.1以降で利用可能です。 ::: -正規表現のキャプチャグループを用いて文字列から部分抽出を行います。完全一致部分は除き、キャプチャされたグループのリストを返します。マッチしない場合やグループがない場合は空リストを返します。 +正規表現のキャプチャグループを用いて、文字列から非グローバルに検索し抽出します。完全一致部分は含まず、キャプチャしたグループのみのリストを返します。マッチしなければ空リストを返します。 例： @@ -658,7 +658,7 @@ regex_extract('Date: 2021-05-20', '(\d{4})-(\d{2})-(\d{2})') -> ['2021', '05', ' ### replace(String: string, SearchPattern: string, Replacement: string) -> string -文字列 `String` のすべての `SearchPattern` を `Replacement` に置換します。例： +`String` 内のすべての `SearchPattern` を `Replacement` に置換します。例： ```bash replace('ab..cd..ef', '..', '**') = 'ab**cd**ef' @@ -673,7 +673,7 @@ replace('ab..cd..ef', '..', '') = 'abcdef' - `all`: すべての `SearchPattern` を置換（`replace/3` と同等） - `leading`: 先頭の `SearchPattern` のみ置換 -- `trailing`: 末尾の `SearchPattern` のみ置換 +- `trailing`: 末尾の `SearchPattern` のみ置換 例： @@ -702,7 +702,7 @@ rm_prefix('foo/bar', 'xxx/') = 'foo/bar' ### rtrim(String: string) -> string -`trim/1` と同様ですが、文字列の末尾の空白文字のみを削除します。例： +`trim/1` と同様ですが、末尾の空白文字のみ削除します。例： ```bash rtrim('\t hello \n') = '\t hello' @@ -713,9 +713,9 @@ rtrim('\t hello \r\n') = '\t hello' `String` を区切り文字 `Separator` で分割し、部分文字列の配列を返します。 -2つ以上の連続した区切り文字は1つとして扱われません。`split/2` は出力結果のトリムと空文字列の除外をデフォルトで行います。空文字列を残したい場合は `split(String, Separator, 'notrim')` を使用してください。 +連続する複数の区切り文字は1つとして扱われず、空文字列が含まれる場合があります。`split/2` はデフォルトで結果をトリムし空文字列を除去します。空文字列を残したい場合は `split(String, Separator, 'notrim')` を使います。 -`Separator` は複数文字でも構いませんが、全体として扱われます。複数の区切り文字を同時に指定したい場合は `tokens` 関数を使用してください。 +区切り文字は複数文字でも可能ですが、全体で1つの区切り文字として扱われます。複数の区切り文字を同時に指定したい場合は `tokens` 関数を使ってください。 例： @@ -735,11 +735,11 @@ split('Sienna Blake; Howell Wise', '; ') = ['Sienna Blake', 'Howell Wise'] `Option` の値は以下の通りです： -- `notrim`: 文字列内のすべての区切り文字を処理し、空文字列を含む可能性あり +- `notrim`: 文字列中のすべての区切り文字を処理し、空文字列を含む可能性あり - `leading`: 先頭の区切り文字のみ処理し、空文字列は含まない - `leading_notrim`: 先頭の区切り文字のみ処理し、空文字列を含む可能性あり - `trailing`: 末尾の区切り文字のみ処理し、空文字列は含まない -- `trailing_notrim`: 末尾の区切り文字のみ処理し、空文字列を含む可能性あり +- `trailing_notrim`: 末尾の区切り文字のみ処理し、空文字列を含む可能性あり 例： @@ -753,11 +753,11 @@ split('a;b;c;', ';', 'trailing_notrim') = ['a;b;c', ''] ### sprintf(Format, ...) -> string -`Format` に従ってフォーマットされた文字列を返します。`Format` 文字列は通常の文字とフォーマット用制御シーケンスを含みます。 +`Format` に従ってフォーマットされた文字列を返します。`Format` は通常の文字とフォーマット制御文字列を含みます。 -制御シーケンスの形式は一般的に `~F.P.PadModC` です。 +制御文字列の形式は一般に `~F.P.PadModC` です。 -`C` は制御シーケンスの種類を示し必須です。`F`, `P`, `Pad`, `Mod` は任意です。詳細は https://www.erlang.org/doc/man/io.html#fwrite-1 を参照してください。 +`C` は制御文字列の種類を決定し必須です。`F`, `P`, `Pad`, `Mod` は省略可能です。詳細は https://www.erlang.org/doc/man/io.html#fwrite-1 を参照してください。 例： @@ -777,7 +777,7 @@ strlen('hello\n') = 6 ### substr(String: string, Start: integer) -> string -文字列 `String` の位置 `Start` から末尾までの部分文字列を返します。文字列の添字は0始まりです。例： +`String` の `Start` 位置（0始まり）から末尾までの部分文字列を返します。例： ```bash substr('hello', 0) = 'hello' @@ -786,7 +786,7 @@ substr('hello world', 6) = 'world' ### substr(String: string, Start: integer, Length: integer) -> string -文字列 `String` の位置 `Start` から最大長 `Length` の部分文字列を返します。添字は0始まりです。例： +`String` の `Start` 位置（0始まり）から最大 `Length` 文字の部分文字列を返します。例： ```bash substr('hello world!', 6, 5) = 'world' @@ -796,7 +796,7 @@ substr('hello world!', 6, 5) = 'world' `String` を `SeparatorList` に含まれる文字で分割し、部分文字列のリストを返します。 -2つ以上の連続した区切り文字は1つとして扱われ、空文字列は発生しません。 +連続する区切り文字は1つとして扱われ、空文字列は発生しません。 例： @@ -815,7 +815,7 @@ tokens('a\rb\nc\r\nd', ';', 'nocrlf') = ['a', 'b', 'c', 'd'] ### trim(String: string) -> string -文字列 `String` の先頭と末尾から空白文字（スペース、タブ、改ページ、改行など）を削除します。`\r\n` はUnicodeのグラフェムクラスタとして扱われるため、まとめて削除されます。例： +`String` の先頭と末尾から空白文字（空白、タブ、改ページ、改行など）を削除します。Unicode標準では `\r\n` は1つのグラフェムクラスタとして扱われるため、まとめて削除されます。例： ```bash trim('\t hello \n') = 'hello' @@ -824,11 +824,11 @@ trim('\t hello \r\n') = 'hello' ### unescape(String: string) -> string -エスケープシーケンスを元の文字に戻します。SQL内でエスケープシーケンスを使う場合は、この関数でアンエスケープしてから処理してください。 +エスケープシーケンスを元の文字に戻します。SQLでエスケープシーケンスを使う場合は、正しく処理するためにこの関数でアンエスケープしてください。 ::: tip -この関数はEMQX v5.7.0以降で導入されました。 +EMQX v5.7.0以降で利用可能です。 ::: @@ -841,13 +841,13 @@ trim('\t hello \r\n') = 'hello' my-device ``` -`\n` で分割したい場合、以下のSQLは期待通り動作しません： +`\n` で分割したい場合、以下のSQLは期待通りに動作しません： ```sql SELECT split(payload, '\n') as device_info FROM 't/#' ``` -出力結果： +出力： ```json { @@ -863,7 +863,7 @@ SELECT split(payload, '\n') as device_info FROM 't/#' SELECT split(payload, unescape('\n')) as device_info FROM 't/#' ``` -出力結果： +出力： ```json { @@ -880,44 +880,44 @@ SELECT split(payload, unescape('\n')) as device_info FROM 't/#' - 標準Cエスケープシーケンス： - - `\n`：改行（LF） - - `\t`：水平タブ（HT） - - `\r`：復帰（CR） - - `\b`：バックスペース（BS） - - `\f`：改ページ（FF） - - `\v`：垂直タブ（VT） - - `\'`：シングルクォート（'） - - `\"`：ダブルクォート（"） - - `\\`：バックスラッシュ（\） - - `\?`：疑問符（?） - - `\a`：アラート（ベル、BEL） + - `\n`（改行 LF） + - `\t`（水平タブ HT） + - `\r`（復帰 CR） + - `\b`（バックスペース BS） + - `\f`（改ページ FF） + - `\v`（垂直タブ VT） + - `\'`（シングルクォート '） + - `\"`（ダブルクォート "） + - `\\`（バックスラッシュ \） + - `\?`（疑問符 ?） + - `\a`（アラート（ベル）BEL） - 16進エスケープコード： - - `\xH...`：`H...` は1文字以上の16進数（0-9, A-F, a-f）で、任意のUTF-32文字をエンコード可能。 + - `\xH...` （`H...` は1文字以上の16進数、任意のutf32文字をエンコード可能） -認識できないエスケープシーケンスや無効なUnicode文字の場合は例外が発生します。 +認識されないエスケープシーケンスや無効なUnicode文字の場合、例外が発生します。 ### upper(String: string) -> string 文字列 `String` の小文字を大文字に変換します。例： ```bash -upper('hello') = 'Hello' +upper('hello') = 'HELLO' ``` ## マップ操作関数 ### map_get(Key: string, Map: map) -> any -`Map` の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。例： +`Map` 内の指定した `Key` の値を返します。`Key` が存在しなければ `undefined` を返します。例： ```bash map_get('msg', json_decode('{"msg": "hello"}')) = 'hello' map_get('data', json_decode('{"msg": "hello"}')) = undefined ``` -### map_get(Key: srting, Map: map, Default: any) -> any +### map_get(Key: string, Map: map, Default: any) -> any `map_get/2` と同様ですが、`Key` が存在しない場合は指定した `Default` を返します。例： @@ -928,7 +928,7 @@ map_get('value', json_decode('{"data": [1.2, 1.3]}'), []) = [] ### map_keys(Map: map) -> array -`Map` のすべてのキーの配列を返します。例： +`Map` のすべてのキーを配列で返します。例： ```bash map_keys(json_decode('{"a": 1, "b": 2}')) = ['a', 'b'] @@ -947,15 +947,15 @@ map_get('a', map_put('a', 2, json_decode('{"a": 1}'))) = 2 ::: tip -この関数はEMQX v5.7.1以降で導入されました。 +EMQX v5.7.1以降で利用可能です。 ::: マップをRedisの `HSET`（または `HMSET`）コマンド用のフィールド名と値のリストに変換します。 -例：`SELECT map_to_redis_hset_args(payload.value) as hset_fields FROM t/1` のように使用し、`hset_fields` をRedisアクションのテンプレート `HMSET name1 ${hset_fields}` に組み込みます。 +例：`SELECT map_to_redis_hset_args(payload.value) as hset_fields FROM t/1` のように使用し、`hset_fields` をRedisアクションのテンプレート `HMSET name1 ${hset_fields}` に埋め込みます。 -例えば、`payload.value` が `{"a" : 1, "b": 2}` の場合、コマンドは `HMSET name1 b 2 a 1` のようになります。マップのフィールド順序は非決定的です。 +例えば、`payload.value` が `{"a" : 1, "b": 2}` の場合、`HMSET name1 b 2 a 1` のようなコマンドになります。マップのフィールド順序は非決定的です。 ### map_to_entries(Map: map) -> array @@ -967,7 +967,7 @@ map_to_entries(json_decode('{"a": 1, "b": 2}')) = [{"key": "a", "value": 1},{"ke ### map_values(Map: map) -> array -`Map` のすべての値の配列を返します。例： +`Map` のすべての値を配列で返します。例： ```bash map_values(json_decode('{"a": 1, "b": 2}')) = [1, 2] @@ -975,7 +975,7 @@ map_values(json_decode('{"a": 1, "b": 2}')) = [1, 2] ### mget(Key: string | array, Map: map) -> any -`Map` の指定した `Key` の値を返します。`Key` が存在しない場合は `undefined` を返します。配列で複数キーを指定すると、ネストしたマップから対応する値を取得します。例： +`Map` 内の指定した `Key` の値を返します。`Key` が存在しなければ `undefined` を返します。配列で複数キーを指定すると、ネストされたマップから対応する値を取得できます。例： ```bash mget('c', json_decode('{"a": {"b": 1}}')) = undefined @@ -985,7 +985,7 @@ mget(['a', 'b'], json_decode('{"a": {"b": 1}}')) = 1 ### mput(Key: string | array, Value: any, Map: map) -> map -`Map` に `Key` と対応する `Value` を挿入し、更新されたマップを返します。`Key` が既に存在する場合は値を上書きします。配列で複数キーを指定すると、ネストしたマップにデータを挿入します。例： +`Map` に `Key` と対応する `Value` を挿入し、更新されたマップを返します。既存の `Key` は上書きされます。配列で複数キーを指定すると、ネストされたマップにデータを挿入できます。例： ```bash mget(['a', 'b'], mput(['a', 'b'], 2, json_decode('{"a": {"b": 1}}'))) = 2 @@ -1017,25 +1017,25 @@ contains(json_decode('{"a": 1}'), [json_decode('{"a": 1}'), json_decode('{"b": 2 ### first(Array: array) -> any -配列 `Array` の最初の要素を返します。`Array` は空であってはなりません。例： +配列 `Array` の最初の要素を返します。`Array` は空であってはいけません。例： ```bash # 正しい例 first(['John', 'David']) = 'John' -# 誤り例 +# 間違い例 first([]) ``` ### last(Array: array) -> any -配列 `Array` の最後の要素を返します。`Array` は空であってはなりません。例： +配列 `Array` の最後の要素を返します。`Array` は空であってはいけません。例： ```bash # 正しい例 last(['John', 'David']) = 'David' -# 誤り例 +# 間違い例 last([]) ``` @@ -1050,20 +1050,20 @@ length([]) = 0 ### nth(N: integer, Array: array) -> any -配列 `Array` のN番目の要素を返します。`N` は配列の長さを超えてはいけません。例： +配列 `Array` のN番目の要素を返します。`N` は配列長以下でなければなりません。例： ```bash # 正しい例 nth(1, [1,2,3]) = 1 -# 誤り例 +# 間違い例 nth(0, [1,2,3]) nth(4, [1,2,3]) ``` ### sublist(Length: integer, Array: array) -> any -配列 `Array` の先頭から最大長 `Length` の部分配列を返します。`Length` が配列長を超える場合は全配列を返します。例： +配列 `Array` の先頭から最大 `Length` 要素の部分配列を返します。`Length` が配列長より大きい場合は全要素を返します。例： ```bash sublist(3, [1,2,3,4]) = [1,2,3] @@ -1072,7 +1072,7 @@ sublist(10, [1,2,3,4]) = [1,2,3,4] ### sublist(Start: integer, Length: integer, Array:array) -> any -`sublist/2` と同様ですが、`Start` で返す開始要素を指定できます。`Start` + `Length` が配列長を超える場合は全配列を返します。例： +`sublist/2` と同様ですが、`Start` で開始位置を指定できます。`Start` + `Length` が配列長より大きい場合は全要素を返します。例： ```bash sublist(2, 10, [1,2,3,4]) = [2,3,4] @@ -1082,7 +1082,7 @@ sublist(2, 10, [1,2,3,4]) = [2,3,4] ### md5(String: string) -> string -任意長の文字列 `String` に対し、128ビット長のMD5ハッシュ値を計算します。ハッシュ値は32桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の128ビット固定長MD5ハッシュ値を計算します。結果は32桁の16進数文字列（小文字）で返します。 例： @@ -1092,7 +1092,7 @@ md5('hello') = '5d41402abc4b2a76b9719d911017c592' ### sha(String: string) -> string -任意長の文字列 `String` に対し、160ビット長のSHA-1ハッシュ値を計算します。ハッシュ値は40桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の160ビット固定長SHA-1ハッシュ値を計算します。結果は40桁の16進数文字列（小文字）で返します。 例： @@ -1102,7 +1102,7 @@ sha('hello') = 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d' ### sha256(String: string) -> string -任意長の文字列 `String` に対し、256ビット長のSHA-2ハッシュ値を計算します。ハッシュ値は64桁の16進数文字列で返され、小文字（a〜f）固定です。 +任意長の文字列 `String` の256ビット固定長SHA-2ハッシュ値を計算します。結果は64桁の16進数文字列（小文字）で返します。 例： @@ -1112,7 +1112,7 @@ sha256('hello') = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9 ## 圧縮・解凍関数 -注意：バイナリデータは直接JSONエンコードできません。`bin2hexstr` 関数で16進文字列に変換してください。 +注：バイナリデータは直接JSONエンコードできないため、16進文字列に変換するには `bin2hexstr` 関数を呼び出す必要があります。 ### gunzip(Data: binary) -> binary | string @@ -1124,7 +1124,7 @@ gunzip(hexstr2bin('1F8B0800000000000013CB48CDC9C9070086A6103605000000')) = 'hell ### gzip(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、gzヘッダーと末尾のチェックサムを含む圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮し、返り値はgzヘッダーと末尾のチェックサムを含みます。例： ```bash bin2hexstr(gzip('hello')) = '1F8B0800000000000013CB48CDC9C9070086A6103605000000' @@ -1140,7 +1140,7 @@ unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' ### zip(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含まない圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮し、返り値はzlibヘッダーと末尾のチェックサムを含みません。例： ```bash bin2hexstr(zip('hello')) = 'CB48CDC9C90700' @@ -1148,7 +1148,7 @@ bin2hexstr(zip('hello')) = 'CB48CDC9C90700' ### zip_compress(Data: binary | string) -> binary -DEFLATEアルゴリズムで `Data` を圧縮し、zlibヘッダーと末尾のチェックサムを含む圧縮結果を返します。例： +DEFLATEアルゴリズムで `Data` を圧縮します。返り値はzlibヘッダーと末尾のチェックサムを含みます。例： ```bash bin2hexstr(zip_compress('hello')) = '789CCB48CDC9C90700062C0215' @@ -1166,7 +1166,7 @@ zip_uncompress(hexstr2bin('789CCB48CDC9C90700062C0215')) = 'hello' ### bitand(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットAND演算結果を返します。入力・出力は符号付き整数です。例： +`Num1` と `Num2` のビットごとのAND演算結果を返します。入力・出力は符号付き整数です。例： ```bash bitand(10, 8) = 8 @@ -1175,7 +1175,7 @@ bitand(-10, -8) = -16 ### bitnot(Num: integer) -> integer -`Num` のビット否定演算結果を返します。入力・出力は符号付き整数です。例： +`Num` のビットごとの否定を返します。入力・出力は符号付き整数です。例： ```bash bitnot(10) = -11 @@ -1204,7 +1204,7 @@ bitsr(-8, 6) = -1 ### bitor(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットOR演算結果を返します。例： +`Num1` と `Num2` のビットごとのOR演算結果を返します。例： ```bash bitor(10, 8) = 10 @@ -1213,7 +1213,7 @@ bitor(-10, -8) = -2 ### bitxor(Num1: integer, Num2: integer) -> integer -`Num1` と `Num2` のビットXOR演算結果を返します。例： +`Num1` と `Num2` のビットごとのXOR演算結果を返します。例： ```bash bitxor(10, 8) = 2 @@ -1222,16 +1222,16 @@ bitxor(-10, -8) = 14 ## ビット列操作関数 -ルールエンジンはビット列操作関数を提供します。例えば `subbits` はビット列から指定長のビットを抽出し、指定データ型に変換します。 +ルールエンジンはビット列操作用の関数を提供します。例として `subbits` はビット列から指定長のビットを抽出し指定型に変換します。 :::tip -`binary` 型はバイト列を表し、各バイトは8ビットで構成されるため、ビット数は8の倍数でなければなりません。 -`bitstring` 型は任意長のビット列を表し、8の倍数でなくてもよいです。 +`binary` 型はバイト列を表し、各バイトは8ビットで構成されるため、バイナリのビット数は8の倍数でなければなりません。 +`bitstring` 型はビット列を表し、任意のビット数を含めることができます。 -つまり、すべての `binary` は `bitstring` ですが、逆は成り立ちません。 +つまり、すべての `binary` は `bitstring` ですが、その逆は必ずしも真ではありません。 -`bitstring` の長さが8の倍数でない場合、JSONなど外部フォーマットに直接シリアライズできません。通常は整数など適切な型に変換する前の中間値として利用されます。 +`bitstring` は長さが8の倍数でない場合、JSONなど外部形式に直接シリアライズできません。通常は整数など適切な型に変換する前の中間値として使われます。 ::: @@ -1255,7 +1255,7 @@ byteszie('你好') = 6 ### subbits(Bin: binary, BitNum: integer) -> integer -バイト列 `Bin` の先頭から長さ `BitNum` のビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, 1, BitNum, 'integer', 'unsigned', 'big')` と同等です。 +バイト列 `Bin` の先頭から `BitNum` ビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, 1, BitNum, 'integer', 'unsigned', 'big')` と同等です。 例： @@ -1272,7 +1272,7 @@ subbits(base64_decode('n05Y'), 8) = 159 ### subbits(Bin: binary, Start: integer, BitNum: integer) -> integer -バイト列 `Bin` の位置 `Start`（1始まり）から長さ `BitNum` のビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, Start, BitNum, 'integer', 'unsigned', 'big')` と同等です。 +バイト列 `Bin` の `Start` 位置（1始まり）から `BitNum` ビットを抽出し、ビッグエンディアンの符号なし整数に変換します。これは `subbits(Bytes, Start, BitNum, 'integer', 'unsigned', 'big')` と同等です。 例： @@ -1289,20 +1289,20 @@ subbits(base64_decode('n05Y'), 9, 4) = 4 ### subbits(Bin: binary, Start: integer, BitNum: integer, OutputType: string, Signedness: string, Endianness: string) -> bitstring | integer | float -バイト列 `Bin` の位置 `Start`（1始まり）から長さ `BitNum` のビットを抽出し、指定したバイト順 `Endianness` と符号属性 `Signedness` に従い、指定型 `OutputType` に変換します。 +バイト列 `Bin` の `Start` 位置（1始まり）から `BitNum` ビットを抽出し、指定したバイト順序 `Endianness` と符号属性 `Signedness` に従い、指定型 `OutputType` に変換します。 -- `OutputType` の可能な値： - - bits（bitstringの略） - - integer - - float +- `OutputType` の値： + - `bits`（bitstringの略） + - `integer` + - `float` -- `Signedness` の可能な値： - - signed - - unsigned +- `Signedness` の値： + - `signed` + - `unsigned` -- `Endianness` の可能な値： - - big - - little +- `Endianness` の値： + - `big` + - `little` `OutputType` が `float` の場合、`Signedness` は無効です。`OutputType` が `bits` の場合、`Signedness` と `Endianness` は無効です。 @@ -1358,7 +1358,7 @@ json_encode([1,2,3]) = '[1,2,3]' ### bin2hexstr(Data: binary) -> string -バイナリデータを対応する16進文字列に変換します。例： +バイナリデータを対応する16進数文字列に変換します。例： ```bash bin2hexstr(zip('hello')) = 'CB48CDC9C90700' @@ -1366,7 +1366,7 @@ bin2hexstr(zip('hello')) = 'CB48CDC9C90700' ### hexstr2bin(Data: string) -> binary -16進文字列を対応するバイナリデータに変換します。例： +16進数文字列を対応するバイナリデータに変換します。例： ```bash unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' @@ -1374,7 +1374,7 @@ unzip(hexstr2bin('CB48CDC9C90700')) = 'hello' ### sqlserver_bin2hexstr(Data: binary | string) -> string -任意のバイナリデータをMicrosoft SQL Serverのバイナリ型に変換します。`0x` プレフィックス付きのHEXエンコード文字列になります。 +任意のバイナリデータをMicrosoft SQL Serverのバイナリ型に変換します。`0x` プレフィックス付きのHEXエンコード文字列となります。 ::: tip @@ -1390,7 +1390,7 @@ sqlserver_bin2hexstr(str_utf16_le('你好')) = '0x604F7D59' ### スキーマレジストリ関数 -EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキーマに基づいて [Protobuf (Protocol Buffers)](https://developers.google.com/protocol-buffers) や [Avro](https://avro.apache.org/) のデータをデコード・エンコードできます。詳細は [Schema Registry](./schema-registry.md) を参照してください。 +EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキーマに従って [Protobuf (Protocol Buffers)](https://developers.google.com/protocol-buffers) や [Avro](https://avro.apache.org/) データのエンコード・デコードをサポートしています。詳細は [スキーマレジストリ](./schema-registry.md) を参照してください。 ### schema_encode(SchemaID: string, Data: map) -> binary @@ -1406,7 +1406,7 @@ EMQXは `schema_encode` と `schema_decode` 関数を使い、指定したスキ ### schema_decode(SchemaID: string, Bin: binary, MsgType: string) -> map -指定したProtobufスキーマで `Bin` をデコードします。スキーマレジストリでスキーマを作成しIDを取得してください。`MsgType` はProtobufスキーマ内の `Data` に対応するメッセージタイプを指定します。 +指定したProtobufスキーマで `Bin` をデコードします。スキーマレジストリでスキーマを作成しIDを取得してください。`MsgType` はProtobufスキーマ内のデータに対応するメッセージタイプを指定します。 ### **Sparkplug B関数** @@ -1416,14 +1416,14 @@ EMQXはSparkplug Bメッセージのデコード・エンコード用の特殊 ### date_to_unix_ts(Unit: string, FormatString: string, DateTimeString: string) -> integer -日時文字列 `DateTimeString` をフォーマット文字列 `FormatString` に従って解析し、指定した時間単位 `Unit` のUnix時間に変換します。 +日時文字列 `DateTimeString` をフォーマット文字列 `FormatString` に従って解析し、指定した時間単位 `Unit` のUnix時刻に変換します。 利用可能な `Unit` は `second`, `millisecond`, `microsecond`, `nanosecond` です。 -`FormatString` で使えるプレースホルダーは以下の通りです： +`FormatString` で使用可能なプレースホルダー： | プレースホルダー | 意味 | 値の範囲 | -| ------ | ---------------------------------- | ----- ---------------- | +| ----------- | ------- | ------------| | `%Y` | 4桁の年 | 0000 - 9999 | | `%m` | 2桁の月 | 01 - 12 | | `%d` | 2桁の日 | 01 - 31 | @@ -1445,13 +1445,13 @@ date_to_unix_ts('second', '%Y-%m-%d %H:%M:%S%:z', '2024-02-23 15:00:00+08:00') = ### date_to_unix_ts(Unit: string, Offset: string | integer, FormatString: string, DateTimeString: string) -> integer -`DateTimeString` にタイムゾーンオフセットが含まれない場合、`Offset` で手動指定できます。その他の動作は `date_to_unix_ts/3` と同様です。`Offset` は文字列または秒数の整数で指定可能です。 +`DateTimeString` にタイムゾーンオフセットが含まれない場合、`Offset` で手動指定できます。その他は `date_to_unix_ts/3` と同様です。`Offset` は文字列か秒数の整数で指定可能です。 文字列の場合、以下の形式をサポートします： - `Z` または `z`：UTCオフセット00:00 - `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット -- `local`：システムのローカルタイムゾーンに対応するオフセット +- `local`：システムのローカルタイムゾーンのオフセット 例： @@ -1463,9 +1463,9 @@ date_to_unix_ts('second', 14400, '%Y-%m-%d %H:%M:%S%:z', '2024-02-23 15:00:00') ### format_date(Unit: string, Offset: string | integer, FormatString: string, Time: Integer) -> string -Unix時間 `Time` を指定フォーマットの日時文字列に変換します。`Unit` はUnix時間の単位、`Offset` は出力日時のタイムゾーンオフセット、`FormatString` は出力フォーマットを表します。 +Unix時刻 `Time` を指定フォーマットの日時文字列に変換します。`Unit` はUnix時刻の単位、`Offset` は出力日時のタイムゾーンオフセット、`FormatString` は出力日時のフォーマットです。 -`date_to_unix_ts/3, 4` を参照し、`Unit`, `Offset`, `FormatString` の値を指定してください。 +`date_to_unix_ts/3, 4` を参照して `Unit`, `Offset`, `FormatString` の値を確認してください。 例： @@ -1479,7 +1479,7 @@ format_date('millisecond', 28800, '%Y-%m-%d %H:%M:%S.%3N%:z', 1708933353472) = ' ### now_rfc3339() -> string -現在のシステム時刻を秒単位のRFC3339形式日時文字列で返します。例： +現在のシステム時刻を秒単位のRFC3339日時文字列で返します。例： ```bash now_rfc3339() = '2024-02-23T10:26:20+08:00' @@ -1487,7 +1487,7 @@ now_rfc3339() = '2024-02-23T10:26:20+08:00' ### now_rfc3339(Unit: string) -> string -`now_rfc3339/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`now_rfc3339/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポート。例： ```bash now_rfc3339('microsecond') = '2024-02-23T10:26:38.009706+08:00' @@ -1503,7 +1503,7 @@ now_timestamp() = 1708913853 ### now_timestamp(Unit: string) -> integer -`now_timestamp/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`now_timestamp/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポート。例： ```bash now_timestamp('microsecond') = 1708913828814315 @@ -1520,7 +1520,7 @@ rfc3339_to_unix_ts('2024-02-23T15:56:30+08:00') = 1708674990 ### rfc3339_to_unix_ts(DateTimeString: string, Unit: string) -> integer -`rfc3339_to_unix_ts/1` と同様ですが、`Unit` で返すUnixタイムスタンプの単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`rfc3339_to_unix_ts/1` と同様ですが、`Unit` で返却するUnixタイムスタンプの単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポート。例： ```bash rfc3339_to_unix_ts('2024-02-23T15:56:30.87Z', 'second') = 1708703790 @@ -1531,11 +1531,11 @@ rfc3339_to_unix_ts('2024-02-23T15:56:30.535904509Z', 'nanosecond') = 17087037905 ### timezone_to_offset_seconds(Offset: string) -> integer -タイムゾーンオフセット文字列を秒数の整数に変換します。以下の形式をサポートします： +タイムゾーンオフセット文字列を秒数の整数に変換します。サポートされる形式： - `Z` または `z`：UTCオフセット00:00 - `±hh[:mm][:ss]` または `±hh[mm][ss]`：UTCからの正負の時間オフセット -- `local`：システムのローカルタイムゾーンに対応するオフセット +- `local`：システムのローカルタイムゾーンのオフセット 例： @@ -1547,7 +1547,7 @@ timezone_to_offset_seconds('local') = 28800 ### unix_ts_to_rfc3339(Time: integer) -> string -秒単位のUnixタイムスタンプをシステムのローカルタイムゾーンでRFC3339準拠の日時文字列に変換します。例： +秒単位のUnixタイムスタンプをシステムのローカルタイムゾーンを用いてRFC3339準拠の日時文字列に変換します。例： ```bash unix_ts_to_rfc3339(1708671600) = '2024-02-23T15:00:00+08:00' @@ -1555,7 +1555,7 @@ unix_ts_to_rfc3339(1708671600) = '2024-02-23T15:00:00+08:00' ### unix_ts_to_rfc3339(Time: integer, Unit: string) -> string -`unix_ts_to_rfc3339/0` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポートします。例： +`unix_ts_to_rfc3339/1` と同様ですが、`Unit` で時間単位を指定できます。`second`, `millisecond`, `microsecond`, `nanosecond` をサポート。例： ```bash unix_ts_to_rfc3339(1708671600766, 'millisecond') = '2024-02-23T15:00:00.766+08:00' @@ -1565,7 +1565,7 @@ unix_ts_to_rfc3339(1708671600766, 'millisecond') = '2024-02-23T15:00:00.766+08:0 ### mongo_date() -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -現在時刻をMongoDBのISODate型または文字列で返します。MongoDB関連のアクションやSQLテストでのみサポートされ、SQLテストでは文字列（例：`ISODate("2024-02-23T15:00:00.123Z")`）を返します。文字列以外の戻り値は他の関数の入力としては現在サポートされていません。 +現在時刻をMongoDBのISODate型または文字列で返します。MongoDB関連アクションとSQLテストでのみサポートされ、SQLテストでは文字列（例：`ISODate("2024-02-23T15:00:00.123Z")`）を返します。文字列以外の戻り値は他の関数の入力としては現在サポートされていません。 例： @@ -1575,7 +1575,7 @@ mongo_date() = 'ISODate("2024-02-23T15:00:00.123Z")' ### mongo_date(Timestamp: integer) -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -指定したミリ秒単位のUnixタイムスタンプをMongoDBのISODate型または文字列に変換します。その他の動作は `mongo_date/0` と同様です。 +指定したミリ秒単位UnixタイムスタンプをMongoDB ISODate型または文字列に変換します。その他は `mongo_date/0` と同様です。 例： @@ -1585,14 +1585,14 @@ mongo_date(now_timestamp('millisecond')) = 'ISODate(2024-02-23T15:48:57.871Z)' ### mongo_date(Timestamp: integer, Unit: string) -> [MongoDB ISODate](https://www.mongodb.com/docs/manual/reference/method/Date/) | string -指定したUnixタイムスタンプをMongoDBのISODate型または文字列に変換します。`Unit` で入力タイムスタンプの単位を指定できます。その他の動作は `mongo_date/0` と同様です。 +指定したUnixタイムスタンプをMongoDB ISODate型または文字列に変換します。`Unit` で入力タイムスタンプの単位を指定可能。その他は `mongo_date/0` と同様です。 -利用可能な `Unit` は： +`Unit` の値： - `second` - `millisecond` - `microsecond` -- `nanosecond` +- `nanosecond` 例： @@ -1624,7 +1624,7 @@ uuid_v4_no_hyphen() = 'd7a39aa4195a42068b962eb9a665503e' 環境変数 `Name` の値を返します。以下の制約があります： -- OS環境変数を読み取る際、`EMQXVAR_` プレフィックスが付加されます。例えば、`getenv('FOO_BAR')` は `EMQXVAR_FOO_BAR` を読み取ります。 +- OS環境変数を読む際は接頭辞 `EMQXVAR_` が付加されます。例えば `getenv('FOO_BAR')` は `EMQXVAR_FOO_BAR` を読みます。 - OS環境変数から読み込んだ値は不変です。 ## 条件関数 @@ -1633,11 +1633,12 @@ uuid_v4_no_hyphen() = 'd7a39aa4195a42068b962eb9a665503e' `Value1` がnullの場合に `Value2` を返します。データフィールドがnullかどうかをチェックし、デフォルト値に置き換えたい場合に便利です。 -例えば、`coalesce(payload.value, 0)` は `payload.value` がnullでなければその値を返し、nullなら0を返します。SQL式の `CASE WHEN is_null(payload.value) THEN 0 ELSE payload.value END` と同等ですが簡潔です。 +例：`coalesce(payload.value, 0)` は `payload.value` がnullでなければその値を、nullなら0を返します。 +SQL式の `CASE WHEN is_null(payload.value) THEN 0 ELSE payload.value END` と同等ですが簡潔です。 ::: tip 注意 -EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefined'` です。 +EMQXルールSQLではnull値の文字列表現はデフォルトで `'undefined'` です。 ::: @@ -1647,6 +1648,6 @@ EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefi ::: tip 注意 -EMQXルールSQLでは、null値の文字列表現はデフォルトで `'undefined'` です。 +EMQXルールSQLではnull値の文字列表現はデフォルトで `'undefined'` です。 ::: diff --git a/ja_JP/data-integration/snowflake.md b/ja_JP/data-integration/snowflake.md index 649a1b482..f37d7be0e 100644 --- a/ja_JP/data-integration/snowflake.md +++ b/ja_JP/data-integration/snowflake.md @@ -1,41 +1,41 @@ # SnowflakeへのMQTTデータ取り込み -[Snowflake](https://www.snowflake.com/en/) は、クラウドベースのデータプラットフォームであり、高いスケーラビリティと柔軟性を備えたデータウェアハウジング、分析、セキュアなデータ共有のソリューションを提供します。構造化データおよび半構造化データの処理に優れ、大量のデータを高速なクエリ性能で保存し、さまざまなツールやサービスとのシームレスな統合を実現します。 +[Snowflake](https://www.snowflake.com/en/) は、クラウドベースのデータプラットフォームであり、高いスケーラビリティと柔軟性を備えたデータウェアハウジング、分析、および安全なデータ共有のソリューションを提供します。構造化データおよび半構造化データの処理に優れており、大量のデータを高速なクエリ性能と多様なツールやサービスとのシームレスな統合を実現しながら保存するよう設計されています。 -本ページでは、EMQXとSnowflake間のデータ統合について詳しく紹介し、ルールおよびSinkの作成方法について実践的なガイダンスを提供します。 +本ページでは、EMQXとSnowflake間のデータ統合について詳しく解説し、ルールおよびSinkの作成方法について実践的なガイダンスを提供します。 -## 動作概要 +## 動作の仕組み -EMQXにおけるSnowflakeデータ統合は、複雑なビジネス開発に容易に対応できる即利用可能な機能です。典型的なIoTアプリケーションでは、EMQXがデバイス接続およびメッセージ送受信を担うIoTプラットフォームとして機能し、Snowflakeはメッセージデータの取り込み、保存、分析を担当するデータストレージおよび処理プラットフォームとして利用されます。 +EMQXにおけるSnowflakeデータ統合は、複雑なビジネス開発に対応可能なすぐに使える機能として提供されています。典型的なIoTアプリケーションでは、EMQXがデバイス接続およびメッセージ伝送を担当するIoTプラットフォームとして機能し、Snowflakeはメッセージデータの取り込み、保存、分析を担うデータストレージおよび処理プラットフォームとして利用されます。 ![snowflake-architecture](./assets/snowflake-architecture.png) -EMQXはルールエンジンとSinkを利用してデバイスイベントやデータをSnowflakeに転送します。エンドユーザーやアプリケーションはSnowflakeのテーブルに格納されたデータにアクセス可能です。具体的なワークフローは以下の通りです。 +EMQXはルールエンジンとSinkを利用してデバイスイベントやデータをSnowflakeに転送します。エンドユーザーやアプリケーションはSnowflakeのテーブルに格納されたデータにアクセスできます。具体的なワークフローは以下の通りです： 1. **デバイスのEMQXへの接続**：IoTデバイスはMQTTプロトコルで正常に接続されるとオンラインイベントをトリガーします。このイベントにはデバイスID、送信元IPアドレス、その他のプロパティ情報が含まれます。 -2. **デバイスメッセージのパブリッシュと受信**：デバイスは特定のトピックを通じてテレメトリやステータスデータをパブリッシュします。EMQXはこれらのメッセージを受信し、ルールエンジン内で比較処理を行います。 -3. **ルールエンジンによるメッセージ処理**：組み込みのルールエンジンはトピックマッチングに基づき特定のソースからのメッセージやイベントを処理します。対応するルールにマッチしたメッセージやイベントに対し、データ形式変換、特定情報のフィルタリング、コンテキスト情報の付加などの処理を実施します。 -4. **Snowflakeへの書き込み**：ルールはSnowflakeのStageにメッセージを書き込み、その後Snowflakeテーブルにロードするアクションをトリガーします。 +2. **デバイスのメッセージパブリッシュと受信**：デバイスは特定のトピックを通じてテレメトリや状態データをパブリッシュします。EMQXはメッセージを受信し、ルールエンジン内で照合します。 +3. **ルールエンジンによるメッセージ処理**：組み込みのルールエンジンはトピックマッチングに基づき特定のソースからのメッセージやイベントを処理します。対応するルールにマッチしたメッセージやイベントを処理し、データフォーマット変換、特定情報のフィルタリング、コンテキスト情報によるメッセージの付加などを行います。 +4. **Snowflakeへの書き込み**：ルールはSnowflake Stageへのメッセージ書き込みアクションをトリガーし、その後Snowflakeテーブルにロードします。 -イベントおよびメッセージデータがSnowflakeに書き込まれた後は、以下のようなビジネスおよび技術用途に利用可能です。 +イベントやメッセージデータがSnowflakeに書き込まれた後は、以下のようなビジネスおよび技術目的で活用できます： - **データアーカイブ**：IoTデータをSnowflakeに安全に長期保存し、コンプライアンスや履歴データの利用を保証します。 - **データ分析**：Snowflakeのデータウェアハウジングおよび分析機能を活用し、リアルタイムまたはバッチ分析を実施。予知保全、運用インサイト、デバイス性能評価などを可能にします。 -## 特長とメリット +## 特長と利点 -EMQXのSnowflakeデータ統合を利用することで、以下の特長とメリットが得られます。 +EMQXにおけるSnowflakeデータ統合を利用することで、以下の特長と利点が得られます： -- **メッセージ変換**：Snowflakeに書き込む前に、EMQXルール内でメッセージの高度な処理や変換が可能で、後続の保存や利用を容易にします。 +- **メッセージ変換**：メッセージはEMQXのルール内で高度に処理・変換されてからSnowflakeに書き込まれるため、その後の保存や利用が容易になります。 - **柔軟なデータ操作**：Snowflake Sinkは書き込むフィールドを選択可能で、ビジネスニーズに応じた効率的かつ動的なストレージ構成を実現します。 - **統合されたビジネスプロセス**：Snowflake Sinkにより、デバイスデータをSnowflakeの豊富なエコシステムアプリケーションと組み合わせ、データ分析やアーカイブなど多様なビジネスシナリオを実現します。 -- **低コストの長期保存**：Snowflakeのスケーラブルなストレージ基盤は、従来のデータベースに比べ低コストでの長期データ保持に最適で、大量のIoTデータ保存に適しています。 +- **低コストの長期保存**：Snowflakeのスケーラブルなストレージ基盤は、従来のデータベースに比べて低コストでの長期データ保持に最適であり、大量のIoTデータ保存に適しています。 -これらの特長により、効率的で信頼性が高くスケーラブルなIoTアプリケーションを構築し、ビジネスの意思決定や最適化に貢献できます。 +これらの特長により、効率的で信頼性が高くスケーラブルなIoTアプリケーションの構築と、ビジネス意思決定や最適化の支援が可能となります。 ## はじめる前に -ここでは、EMQXでSnowflake Sinkを作成する前に必要な準備について説明します。 +このセクションでは、EMQXでSnowflake Sinkを作成する前に必要な準備について説明します。 ### 前提条件 @@ -44,41 +44,94 @@ EMQXのSnowflakeデータ統合を利用することで、以下の特長とメ ### Snowflake ODBCドライバーの初期化 -EMQXがSnowflakeと通信し効率的にデータ転送を行うために、Snowflake Open Database Connectivity（ODBC）ドライバーのインストールと設定が必要です。これは通信の橋渡し役となり、データの適切なフォーマット化、認証、転送を保証します。 +EMQXがSnowflakeと通信し、効率的にデータ転送を行うためには、SnowflakeのOpen Database Connectivity（ODBC）ドライバーをインストールおよび設定する必要があります。これは通信の橋渡し役として機能し、データの適切なフォーマット、認証、転送を保証します。 詳細は公式の[ODBC Driver](https://docs.snowflake.com/en/developer-guide/odbc/odbc)ページおよび[ライセンス契約](https://sfc-repo.snowflakecomputing.com/odbc/Snowflake_ODBC_Driver_License_Agreement.pdf)を参照してください。 #### Linux -以下のスクリプトを実行してSnowflake ODBCドライバーをインストールし、`odbc.ini`ファイルを設定します。 +EMQXはDebian系（Ubuntuなど）システム向けにSnowflake ODBCドライバーの迅速な展開と必要なシステム設定を行う[インストールスクリプト](https://github.com/emqx/emqx/blob/master/scripts/install-snowflake-driver.sh)を提供しています。 +::: tip 注意 + +このスクリプトはテスト用であり、本番環境でのODBCドライバー設定方法として推奨するものではありません。公式の[Linux向けインストール手順](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux)を参照してください。 + +::: + +**インストールスクリプトの実行** + +`scripts/install-snowflake-driver.sh`スクリプトをローカルマシンにコピーし、`chmod a+x`で実行権限を付与した後、`sudo`で実行します： + +```bash +chmod a+x scripts/install-snowflake-driver.sh +sudo ./scripts/install-snowflake-driver.sh ``` -scripts/install-snowflake-driver.sh + +スクリプトはSnowflake ODBCの`.deb`インストールパッケージ（例：`snowflake-odbc-3.4.1.x86_64.deb`）をカレントディレクトリに自動ダウンロードし、ドライバーをインストール、以下のシステム設定ファイルを更新します： + +- `/etc/odbc.ini`：Snowflakeデータソース設定を追加 +- `/etc/odbcinst.ini`：Snowflakeドライバーパスを登録 + +**設定例** + +`/etc/odbc.ini`の内容を確認するには以下を実行： + ``` +emqx@emqx-0:~$ cat /etc/odbc.ini -::: tip 注意 +[snowflake] +Description=SnowflakeDB +Driver=SnowflakeDSIIDriver +Locale=en-US +PORT=443 +SSL=on -このスクリプトはテスト用であり、本番環境でのODBCドライバー設定方法の推奨ではありません。公式の[Linux向けインストール手順](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux)を参照してください。 +[ODBC Data Sources] +snowflake = SnowflakeDSIIDriver +``` -::: +`/etc/odbcinst.ini`の内容を確認するには以下を実行： + +``` +emqx@emqx-0:~$ cat /etc/odbcinst.ini + +[ODBC Driver 18 for SQL Server] +Description=Microsoft ODBC Driver 18 for SQL Server +Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.5.so.1.1 +UsageCount=1 + +[ODBC Driver 17 for SQL Server] +Description=Microsoft ODBC Driver 17 for SQL Server +Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1 +UsageCount=1 + +[SnowflakeDSIIDriver] +APILevel=1 +ConnectFunctions=YYY +Description=Snowflake DSII +Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so +DriverODBCVer=03.52 +SQLLevel=1 +UsageCount=1 +``` #### macOS -macOSでSnowflake ODBCドライバーをインストールおよび設定する手順は以下の通りです。 +macOSでSnowflake ODBCドライバーをインストールおよび設定するには、以下の手順に従ってください： -1. unixODBCをインストール（例）: +1. unixODBCをインストールします。例： ``` brew install unixodbc ``` -2. [iODBCのダウンロードとインストール](https://github.com/openlink/iODBC/releases/download/v3.52.16/iODBC-SDK-3.52.16-macOS11.dmg)。 +2. [iODBCをダウンロードおよびインストール](https://github.com/openlink/iODBC/releases/download/v3.52.16/iODBC-SDK-3.52.16-macOS11.dmg)します。 -3. [Snowflake ODBCドライバーのダウンロードとインストール](https://sfc-repo.snowflakecomputing.com/odbc/macuniversal/3.3.2/snowflake_odbc_mac_64universal-3.3.2.dmg)。 +3. [Snowflake ODBCドライバーをダウンロードおよびインストール](https://sfc-repo.snowflakecomputing.com/odbc/macuniversal/3.3.2/snowflake_odbc_mac_64universal-3.3.2.dmg)します。 -4. 詳細なインストールおよび設定手順は[macOS向けODBCドライバーのインストールと設定](https://docs.snowflake.com/en/developer-guide/odbc/odbc-mac)を参照。 +4. 詳細なインストールおよび設定手順は[macOS向けODBCドライバーのインストールと設定](https://docs.snowflake.com/en/developer-guide/odbc/odbc-mac)を参照してください。 -5. インストール後、以下の設定ファイルを更新： +5. インストール後、以下の設定ファイルを更新します： - Snowflake ODBCドライバーの権限と設定を更新： @@ -87,7 +140,7 @@ macOSでSnowflake ODBCドライバーをインストールおよび設定する echo 'ODBCInstLib=libiodbcinst.dylib' >> /opt/snowflake/snowflakeodbc/lib/universal/simba.snowflake.ini ``` - - `~/.odbc.ini`ファイルを作成または更新し、ODBC接続を設定： + - ODBC接続を設定するため、`~/.odbc.ini`ファイルを作成または更新： ``` cat << EOF > ~/.odbc.ini @@ -108,11 +161,11 @@ macOSでSnowflake ODBCドライバーをインストールおよび設定する ### ユーザーアカウントとデータベースの作成 -Snowflake ODBCドライバーのインストール後、データ取り込み用のユーザーアカウント、データベース、および関連リソースを設定する必要があります。以下の認証情報は後でEMQXのコネクターおよびSink設定時に使用します。 +Snowflake ODBCドライバーのインストールが完了したら、データ取り込み用のユーザーアカウント、データベース、および関連リソースを設定する必要があります。以下の認証情報は後でEMQXのコネクターおよびSink設定時に使用します： -| 項目 | 値 | +| 項目 | 値 | | ------------------------ | ------------------------------------------------ | -| Data Source Name (DSN) | `snowflake` | +| データソース名（DSN） | `snowflake` | | ユーザー名 | `snowpipeuser` | | パスワード | `Snowpipeuser99` | | データベース名 | `testdatabase` | @@ -124,7 +177,7 @@ Snowflake ODBCドライバーのインストール後、データ取り込み用 #### RSA鍵ペアの生成 -Snowflakeへの安全な接続のため、以下のコマンドでRSA鍵ペアを生成します。 +Snowflakeへの安全な接続のため、以下のコマンドでRSA鍵ペアを生成します： ```bash openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out snowflake_rsa_key.private.pem -nocrypt @@ -135,66 +188,64 @@ openssl rsa -in snowflake_rsa_key.private.pem -pubout -out snowflake_rsa_key.pub #### SQLを使ったSnowflakeリソースのセットアップ -ODBCドライバーの設定とRSA鍵ペアの生成後、Snowflakeのデータベース、テーブル、ステージ、パイプをSQLコマンドで作成します。 +ODBCドライバーの設定とRSA鍵ペアの生成が完了したら、SnowflakeコンソールのSQL Worksheetで以下のSQLを実行し、必要なデータベース、テーブル、ステージ、パイプを作成します： -1. SnowflakeコンソールのSQLワークシートで以下のSQLを実行し、データベース、テーブル、ステージ、パイプを作成します。 +```sql +USE ROLE accountadmin; - ```sql - USE ROLE accountadmin; - - CREATE DATABASE IF NOT EXISTS testdatabase; - - CREATE OR REPLACE TABLE testdatabase.public.emqx ( - clientid STRING, - topic STRING, - payload STRING, - publish_received_at TIMESTAMP_LTZ - ); - - CREATE STAGE IF NOT EXISTS testdatabase.public.emqx - FILE_FORMAT = (TYPE = CSV PARSE_HEADER = TRUE FIELD_OPTIONALLY_ENCLOSED_BY = '"') - COPY_OPTIONS = (ON_ERROR = CONTINUE PURGE = TRUE); - - CREATE PIPE IF NOT EXISTS testdatabase.public.emqx AS - COPY INTO testdatabase.public.emqx - FROM @testdatabase.public.emqx - MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE; - ``` +CREATE DATABASE IF NOT EXISTS testdatabase; -2. 新規ユーザーを作成し、そのユーザーにRSA公開鍵を設定します。 +CREATE OR REPLACE TABLE testdatabase.public.emqx ( + clientid STRING, + topic STRING, + payload STRING, + publish_received_at TIMESTAMP_LTZ +); - ```sql - CREATE USER IF NOT EXISTS snowpipeuser - PASSWORD = 'Snowpipeuser99' - MUST_CHANGE_PASSWORD = FALSE; - - ALTER USER snowpipeuser SET RSA_PUBLIC_KEY = ' - - - - - '; - ``` +CREATE STAGE IF NOT EXISTS testdatabase.public.emqx +FILE_FORMAT = (TYPE = CSV PARSE_HEADER = TRUE FIELD_OPTIONALLY_ENCLOSED_BY = '"') +COPY_OPTIONS = (ON_ERROR = CONTINUE PURGE = TRUE); - ::: tip +CREATE PIPE IF NOT EXISTS testdatabase.public.emqx AS +COPY INTO testdatabase.public.emqx +FROM @testdatabase.public.emqx +MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE; +``` - PEMファイルの`-----BEGIN PUBLIC KEY-----`および`-----END PUBLIC KEY-----`の行は削除し、残りの内容は改行を保持して含めてください。 +次に、新規ユーザーを作成し、そのユーザーにRSA公開鍵を設定します： - ::: +```sql +CREATE USER IF NOT EXISTS snowpipeuser + PASSWORD = 'Snowpipeuser99' + MUST_CHANGE_PASSWORD = FALSE; -3. 必要なロールを作成し、ユーザーに割り当てます。 +ALTER USER snowpipeuser SET RSA_PUBLIC_KEY = ' + + + + +'; +``` - ```sql - CREATE OR REPLACE ROLE snowpipe; - - GRANT USAGE ON DATABASE testdatabase TO ROLE snowpipe; - GRANT USAGE ON SCHEMA testdatabase.public TO ROLE snowpipe; - GRANT INSERT, SELECT ON testdatabase.public.emqx TO ROLE snowpipe; - GRANT READ, WRITE ON STAGE testdatabase.public.emqx TO ROLE snowpipe; - GRANT OPERATE, MONITOR ON PIPE testdatabase.public.emqx TO ROLE snowpipe; - GRANT ROLE snowpipe TO USER snowpipeuser; - ALTER USER snowpipeuser SET DEFAULT_ROLE = snowpipe; - ``` +::: tip + +PEMファイルの`-----BEGIN PUBLIC KEY-----`および`-----END PUBLIC KEY-----`の行は削除し、改行を保持したまま残りの内容を設定してください。 + +::: + +最後に、ユーザーに必要な権限を付与するロールを作成し、割り当てます： + +```sql +CREATE OR REPLACE ROLE snowpipe; + +GRANT USAGE ON DATABASE testdatabase TO ROLE snowpipe; +GRANT USAGE ON SCHEMA testdatabase.public TO ROLE snowpipe; +GRANT INSERT, SELECT ON testdatabase.public.emqx TO ROLE snowpipe; +GRANT READ, WRITE ON STAGE testdatabase.public.emqx TO ROLE snowpipe; +GRANT OPERATE, MONITOR ON PIPE testdatabase.public.emqx TO ROLE snowpipe; +GRANT ROLE snowpipe TO USER snowpipeuser; +ALTER USER snowpipeuser SET DEFAULT_ROLE = snowpipe; +``` ## コネクターの作成 @@ -209,55 +260,54 @@ Snowflake Sinkを追加する前に、EMQXでSnowflakeとの接続を確立す 4. コネクター名を入力します。英数字の組み合わせで、ここでは `my-snowflake` と入力します。 5. 接続情報を入力します。 - - **Account**：Snowflakeの組織IDとアカウント名をハイフン（`-`）で区切って入力します。これはSnowflakeプラットフォームのURLの一部で、Snowflakeコンソールで確認可能です。 - - - **Server Host**：SnowflakeのエンドポイントURLで、通常は `-.snowflakecomputing.com` の形式です。`-` はご自身のSnowflakeインスタンス固有のサブドメインに置き換えてください。 - - - **Data Source Name (DSN)**：ODBCドライバー設定時に`.odbc.ini`で設定した`snowflake`を入力します。 - + + - **Server Host**：SnowflakeのエンドポイントURLで、通常は `-.snowflakecomputing.com` の形式です。`-` はご自身のSnowflakeインスタンスに合わせて置き換えてください。 + + - **Data Source Name (DSN)**：ODBCドライバー設定時に`.odbc.ini`ファイルで設定した`snowflake`を入力します。 + - **Username**：前述の設定で作成した`snowpipeuser`を入力します。 - - - **Password**：ODBC経由でユーザー名/パスワード認証を行う場合のパスワード。任意入力です。 - + + - **Password**：ODBC経由でのユーザー名/パスワード認証に使用するパスワードです。この項目は任意です： + - ここにパスワード（例：`Snowpipeuser99`）を入力するか、 - - `/etc/odbc.ini`で設定するか、 - - キーペア認証を使用する場合は空欄のままにします。 - + - `/etc/odbc.ini`に設定するか、 + - キーペア認証を使用する場合は空欄にします。 + ::: tip - - 認証にはパスワードかプライベートキーのいずれかを使用し、両方は使用しません。どちらも設定しない場合は、適切な認証情報が`/etc/odbc.ini`に設定されていることを確認してください。 - + + 認証にはパスワードかプライベートキーのいずれか一方を使用してください。両方設定しない場合は、適切な認証情報が`/etc/odbc.ini`に設定されていることを確認してください。 + ::: - - - **Private Key Path**：ODBC経由でキーペア認証を行うためのプライベートRSA鍵ファイルの絶対パス。クラスタの全ノードで同一パスである必要があります。`file://`で始まる形式で指定します（例：`file:///etc/emqx/certs/snowflake_rsa_key.private.pem`）。 - - - **Private Key Password**：プライベートRSA鍵ファイルが暗号化されている場合の復号パスワード。OpenSSLの`-nocrypt`オプションで生成した鍵は空欄のままにします。 - - - **Proxy**：HTTPプロキシサーバー経由でSnowflakeに接続する場合の設定。HTTPSプロキシはサポートしていません。デフォルトはプロキシなし。プロキシを有効にする場合は`Enable Proxy`を選択し、以下を入力します。 - - - **Proxy Host**：プロキシサーバーのホスト名またはIPアドレス。 - - **Proxy Port**：プロキシサーバーのポート番号。 - -6. 暗号化接続を確立する場合は、**Enable TLS** トグルをオンにします。TLS接続の詳細は[外部リソースアクセスのTLS](../network/overview.md/#tls-for-external-resource-access)を参照してください。 + + - **Private Key Path**：ODBC経由でSnowflakeに認証するためのプライベートRSA鍵の絶対パスです。クラスター内のすべてのノードで同じパスである必要があります。パスは`file://`で始まる必要があります。例：`file:///etc/emqx/certs/snowflake_rsa_key.private.pem` + + - **Private Key Password**：プライベートRSA鍵ファイルが暗号化されている場合の復号パスワードです。暗号化なし（OpenSSLの`-nocrypt`オプション使用）で生成した場合は空欄にします。 + + - **Proxy**：HTTPプロキシサーバー経由でSnowflakeに接続するための設定です。HTTPSプロキシはサポートされていません。デフォルトはプロキシなしです。プロキシを有効にするには`Enable Proxy`を選択し、以下を入力します： + + - **Proxy Host**：プロキシサーバーのホスト名またはIPアドレス + - **Proxy Port**：プロキシサーバーのポート番号 + +6. 暗号化接続を確立したい場合は、**Enable TLS** トグルスイッチをオンにします。TLS接続の詳細は[外部リソースアクセスのTLS](../network/overview.md/#tls-for-external-resource-access)を参照してください。 7. 詳細設定（任意）：[Advanced Settings](#advanced-settings)を参照してください。 -8. **Create**をクリックする前に、**Test Connectivity**をクリックしてコネクターがSnowflakeに接続できるかテスト可能です。 +8. **Create**をクリックする前に、**Test Connectivity**でコネクターがSnowflakeに接続できるかテスト可能です。 -9. 最後に、**Create**ボタンをクリックしてコネクター作成を完了します。 +9. 最後に、画面下部の **Create** ボタンをクリックしてコネクター作成を完了します。 -これでコネクターの作成が完了し、次にルールとSinkを作成してSnowflakeへのデータ書き込み方法を指定できます。 +これでコネクター作成が完了し、次にルールとSinkを作成してSnowflakeへのデータ書き込み方法を指定できます。 -## Snowflake Sinkを使ったルールの作成 +## Snowflake Sinkを用いたルールの作成 -このセクションでは、EMQXでソースMQTTトピック `t/#` からのメッセージを処理し、処理結果を設定済みのSnowflake Sink経由でSnowflakeに書き込むルールの作成方法を示します。 +このセクションでは、EMQXでソースMQTTトピック `t/#` からのメッセージを処理し、処理結果を設定済みのSnowflake Sinkを通じてSnowflakeに書き込むルールの作成方法を示します。 1. ダッシュボードの **Integration** -> **Rules** ページに移動します。 2. 右上の **Create** ボタンをクリックします。 -3. ルールIDに `my_rule` を入力し、SQLエディターに以下のルールSQLを入力します。 +3. ルールIDに `my_rule` を入力し、SQLエディターに以下のルールSQLを入力します： ```sql SELECT @@ -271,96 +321,96 @@ Snowflake Sinkを追加する前に、EMQXでSnowflakeとの接続を確立す ::: tip - SQLに不慣れな場合は、**SQL Examples**や**Enable Debug**をクリックしてルールSQLの学習やテストが可能です。 + SQLに不慣れな場合は、**SQL Examples**をクリックし、**Enable Debug**を有効にしてルールSQLの結果を学習・テストできます。 ::: ::: tip - - Snowflake連携では、選択するフィールドはSnowflakeで定義したテーブルのカラム数および名前と完全に一致させる必要があります。余分なフィールドを追加したり、`*`で全選択することは避けてください。 - + + Snowflake連携では、選択するフィールドはSnowflakeで定義したテーブルのカラム数および名前と完全に一致させる必要があります。追加フィールドの追加や`*`による全選択は避けてください。 + ::: -4. アクションを追加し、**Action Type**ドロップダウンから`Snowflake`を選択します。アクションドロップダウンはデフォルトの`create action`のままにするか、既存のSnowflakeアクションを選択します。ここでは新規Sinkを作成し、ルールに追加します。 +4. アクションを追加し、**Action Type**ドロップダウンから`Snowflake`を選択します。アクションドロップダウンはデフォルトの`create action`のままにするか、既存のSnowflakeアクションを選択します。ここでは新規Sinkを作成しルールに追加します。 -5. Sinkの名前（例：`snowflake_sink`）と簡単な説明を入力します。 +5. Sink名（例：`snowflake_sink`）と簡単な説明を入力します。 -6. 先ほど作成した`my-snowflake`コネクターをコネクタードロップダウンから選択します。ドロップダウン横の作成ボタンをクリックして新規コネクターをポップアップで素早く作成することも可能です。必要な設定パラメータは[コネクターの作成](#コネクターの作成)を参照してください。 +6. 先ほど作成した`my-snowflake`コネクターをコネクタードロップダウンから選択します。ドロップダウン横の作成ボタンをクリックするとポップアップで新規コネクター作成も可能です。必要な設定パラメータは[コネクターの作成](#コネクターの作成)を参照してください。 -7. 以下の設定を行います。 +7. 以下の設定を行います： - - **Database Name**：`testdatabase`。EMQXデータ保存用に作成したSnowflakeデータベース名。 - - **Schema**：`public`。`testdatabase`内のデータテーブルが存在するスキーマ名。 - - **Stage**：`emqx`。Snowflakeで作成した、テーブルにロードする前のデータを保持するステージ名。 - - **Pipe**：`emqx`。ステージからテーブルへのロード処理を自動化するパイプ名。 - - **Pipe User**：`snowpipeuser`。パイプ管理権限を持つSnowflakeユーザー名。 - - **Private Key**：プライベートRSA鍵のパス（例：`file://`）またはRSAプライベート鍵ファイルの内容。安全な認証に必要で、パイプへの安全なアクセスに使用します。ファイルパス指定の場合はクラスター全ノードで同一かつEMQXアプリケーションユーザーがアクセス可能である必要があります。 + - **Database Name**：`testdatabase`を入力。EMQXデータ保存用に作成したSnowflakeデータベースです。 + - **Schema**：`public`を入力。`testdatabase`内のデータテーブルが存在するスキーマです。 + - **Stage**：`emqx`を入力。Snowflakeでデータをテーブルにロードする前に保持するステージです。 + - **Pipe**：`emqx`を入力。ステージからテーブルへのロードを自動化するパイプです。 + - **Pipe User**：`snowpipeuser`を入力。パイプ管理権限を持つSnowflakeユーザーです。 + - **Private Key**：プライベートRSA鍵のパス（例：`file://`）またはRSAプライベート鍵ファイルの内容を入力します。これは安全な認証に必要で、パスを使用する場合はクラスター内全ノードで共通かつEMQXアプリケーションユーザーがアクセス可能である必要があります。 -8. **Upload Mode**を選択します。現在は`Aggregated Upload`のみサポート。複数のルールトリガー結果を1つのファイル（例：CSV）にまとめてSnowflakeにアップロードし、ファイル数を減らして書き込み効率を向上させます。 +8. **Upload Mode**を選択します。現在は`Aggregated Upload`のみサポートされています。この方式は複数のルールトリガー結果を1つのファイル（例：CSVファイル）にまとめてSnowflakeにアップロードし、ファイル数を減らして書き込み効率を向上させます。 -9. **Aggregation Type**を選択します。現在は`csv`のみサポート。データはカンマ区切りCSV形式でSnowflakeにステージングされます。 +9. **Aggregation Type**を選択します。現在は`csv`のみサポートされており、データはカンマ区切りCSV形式でSnowflakeにステージングされます。 - - **Column Order**：ドロップダウンから列の並び順を選択します。生成されるCSVファイルは選択した列の順に並び、未選択列はアルファベット順に並びます。 + - **Column Order**：ドロップダウンから列の並び順を選択します。生成されるCSVファイルは選択した列順にソートされ、未選択列はアルファベット順に続きます。 - - **Max Records**：集約をトリガーする最大レコード数を設定します。例えば`1000`に設定すると、1000件のレコード収集後にアップロードが行われ、時間間隔がリセットされます。 + - **Max Records**：集約をトリガーする最大レコード数を設定します。例えば`1000`に設定すると1000レコード収集後にアップロードされ、時間間隔がリセットされます。 - - **Time Interval**：集約を行う時間間隔（秒）を設定します。例えば`60`に設定すると、最大レコード数に達していなくても60秒ごとにデータがアップロードされ、最大レコード数がリセットされます。 + - **Time Interval**：集約が行われる時間間隔（秒）を設定します。例えば`60`に設定すると、最大レコード数に達していなくても60秒ごとにデータがアップロードされ、最大レコード数がリセットされます。 -10. **フォールバックアクション（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義可能です。プライマリSinkがメッセージ処理に失敗した場合にトリガーされます。詳細は[フォールバックアクション](./data-bridges.md#fallback-actions)を参照してください。 +10. **フォールバックアクション（任意）**：メッセージ配信失敗時の信頼性向上のため、1つ以上のフォールバックアクションを定義できます。詳細は[フォールバックアクション](./data-bridges.md#fallback-actions)を参照してください。 -11. **詳細設定**を展開し、必要に応じて高度な設定オプションを構成します（任意）。詳細は[Advanced Settings](#advanced-settings)を参照してください。 +11. **詳細設定**を展開し、必要に応じて高度な設定オプションを調整します（任意）。詳細は[Advanced Settings](#advanced-settings)を参照してください。 -12. 残りの設定はデフォルト値のままにし、**Create**ボタンをクリックしてSink作成を完了します。作成成功後はルール作成画面に戻り、新規Sinkがルールアクションに追加されます。 +12. 残りの設定はデフォルト値を使用し、**Create**ボタンをクリックしてSink作成を完了します。作成成功後はルール作成画面に戻り、新規Sinkがルールのアクションに追加されます。 -13. ルール作成画面で**Create**をクリックし、ルール作成全体を完了します。 +13. ルール作成画面で**Create**ボタンをクリックし、ルール作成全体を完了します。 -これでルールの作成が完了しました。**Rules**ページで新規作成したルールを確認でき、**Actions (Sink)**タブで新しいSnowflake Sinkも確認可能です。 +これでルールが正常に作成されました。**Rules**ページで新規ルールを確認でき、**Actions (Sink)**タブで新しいSnowflake Sinkも確認できます。 -また、**Integration** -> **Flow Designer**をクリックするとトポロジーを視覚的に確認できます。トポロジーは、トピック`t/#`配下のメッセージがルール`my_rule`で解析され、Snowflakeに書き込まれる流れを示します。 +また、**Integration** -> **Flow Designer**でトポロジーを表示可能です。トポロジーはトピック`t/#`のメッセージがルール`my_rule`で解析され、Snowflakeに書き込まれる流れを視覚的に示します。 ## ルールのテスト -ここでは設定したルールのテスト方法を説明します。 +このセクションでは、設定したルールのテスト方法を示します。 ### テストメッセージのパブリッシュ -MQTTXを使い、トピック`t/1`にメッセージをパブリッシュします。 +MQTTXを使用してトピック`t/1`にメッセージをパブリッシュします： ```bash mqttx pub -i emqx_c -t t/1 -m '{ "msg": "Hello Snowflake" }' ``` -この操作を数回繰り返し、複数のテストメッセージを生成してください。 +複数回繰り返してテストメッセージを生成してください。 ### Snowflake内のデータ確認 -テストメッセージ送信後、Snowflakeにデータが正常に書き込まれているかを確認します。 +テストメッセージ送信後、Snowflakeにデータが正常に書き込まれたかを確認します。 1. SnowflakeのWebインターフェースにアクセスし、認証情報でSnowflakeコンソールにログインします。 -2. コンソールで以下のSQLクエリを実行し、ルールで書き込まれた`emqx`テーブルのデータを表示します。 +2. コンソールで以下のSQLクエリを実行し、ルールによって書き込まれた`emqx`テーブルのデータを表示します： ``` SELECT * FROM testdatabase.public.emqx; ``` - これにより、`emqx`テーブルにアップロードされたすべてのレコード（`clientid`、`topic`、`payload`、`publish_received_at`フィールドを含む）が表示されます。 + これにより、`clientid`、`topic`、`payload`、`publish_received_at`フィールドを含む全レコードが表示されます。 -3. 送信したテストメッセージ（例：`{ "msg": "Hello Snowflake" }`）や、トピック、タイムスタンプなどのメタデータが確認できるはずです。 +3. 送信したテストメッセージ（例：`{ "msg": "Hello Snowflake" }`）やトピック、タイムスタンプなどのメタデータが確認できます。 ## 詳細設定 このセクションでは、Snowflake Sinkの詳細設定オプションについて説明します。ダッシュボードのSink設定画面で**Advanced Settings**を展開し、用途に応じて以下のパラメータを調整可能です。 -| 項目名 | 説明 | デフォルト値 | -| ------------------------- | ----------------------------------------------------------------------------------------- | -------------- | -| **Max Retries** | アップロード失敗時の最大リトライ回数を設定します。例：`3`で3回までリトライ可能。 | `3` | -| **Buffer Pool Size** | EMQXとSnowflake間のデータフローを管理するバッファワーカープロセス数を指定します。これらのワーカーはデータを一時的に保持・処理し、性能最適化とスムーズなデータ送信を支えます。 | `16` | -| **Request TTL** | バッファに入ったリクエストが有効とみなされる最大時間（秒）を指定します。TTLを超えてバッファ内に滞留、または送信後にSnowflakeからの応答やアックが得られない場合、リクエストは期限切れと判断されます。 | | -| **Health Check Interval** | Snowflakeとの接続状態をSinkが自動的にチェックする間隔（秒）を指定します。 | `15` | -| **Max Buffer Queue Size** | Snowflake Sinkの各バッファワーカーがバッファリング可能な最大バイト数を指定します。ワーカーはデータを一時保持し、効率的なデータストリーム処理を実現します。システム性能やデータ転送要件に応じて調整してください。 | `256` | -| **Query Mode** | リクエストモードを`synchronous`または`asynchronous`から選択し、メッセージ送信を最適化します。非同期モードではSnowflakeへの書き込みがMQTTメッセージパブリッシュをブロックしませんが、クライアントがSnowflake到達前にメッセージを受信する可能性があります。 | `Asynchronous` | -| **Batch Size** | EMQXからSnowflakeへ一度に転送するデータバッチの最大サイズを指定します。サイズ調整により転送効率や性能を最適化可能です。
`1`に設定すると、データはバッチ化せず個別に送信されます。 | `1` | -| **Inflight Window** | 送信済みだが応答やアックをまだ受け取っていない「インフライト」キューリクエストの最大数を制御します。
`Request Mode`が`asynchronous`の場合、この設定は特に重要です。同一MQTTクライアントからのメッセージを厳密に順序処理する必要がある場合は`1`に設定してください。 | `100` | -| **Connect Timeout** | Snowflakeへの接続確立を待つ最大時間（秒）を指定します。例：`30`秒。接続できない場合はリトライ（Max Retriesに基づく）またはエラーを返します。ネットワーク遅延や接続信頼性管理に有用です。 | `15` | -| **HTTP Pipelining** | 応答待ち前に送信可能なHTTPリクエストの最大数を指定します。 | `100` | -| **Connection Pool Size** | EMQXがSnowflakeに同時に維持可能な接続数を定義します。大きいほど高負荷時の同時リクエスト数が増えますが、システムリソース消費も増加します。 | `8` | +| 項目名 | 説明 | デフォルト値 | +| ------------------------ | ------------------------------------------------------------ | -------------- | +| **Max Retries** | アップロード失敗時の最大リトライ回数を設定します。例：`3`で3回までリトライ可能。 | `3` | +| **Buffer Pool Size** | EMQXとSnowflake間のデータフローを管理するバッファワーカープロセス数を指定します。これらのワーカーはデータを一時保存・処理し、送信前のパフォーマンス最適化とスムーズなデータ転送に重要です。 | `16` | +| **Request TTL** | バッファに入ったリクエストが有効とみなされる最大時間（秒）を指定します。リクエストがこの時間を超えてバッファ内にあるか、Snowflakeからの応答やアックを受け取れなかった場合、リクエストは期限切れとみなされます。 | | +| **Health Check Interval** | Snowflakeとの接続状態を自動的にチェックする間隔（秒）を指定します。 | `15` | +| **Max Buffer Queue Size** | Snowflake Sinkの各バッファワーカーが一時的に保持できる最大バイト数を指定します。バッファワーカーはデータを一時保存し、効率的にSnowflakeへ送信します。システム性能やデータ転送要件に応じて調整してください。 | `256` | +| **Query Mode** | `synchronous`または`asynchronous`のリクエストモードを選択し、メッセージ送信を最適化します。非同期モードではSnowflakeへの書き込みがMQTTメッセージのパブリッシュ処理をブロックしませんが、クライアントがSnowflake到達前にメッセージを受信する可能性があります。 | `Asynchronous` | +| **Batch Size** | EMQXからSnowflakeへ一度に送信するデータバッチの最大サイズを指定します。サイズを調整することでデータ転送効率と性能を最適化できます。
`1`に設定すると、データレコードはバッチ化されず個別に送信されます。 | `1` | +| **Inflight Window** | 「インフライトキューリクエスト」とは、送信済みでまだ応答やアックを受け取っていないリクエストを指します。この設定はSnowflakeとの通信中に同時に存在可能なインフライトリクエストの最大数を制御します。
**Request Mode**が`asynchronous`の場合、このパラメータは特に重要です。同一MQTTクライアントからのメッセージを厳密に順序処理したい場合は`1`に設定してください。 | `100` | +| **Connect Timeout** | Snowflakeへの接続確立を待機する最大時間（秒）を指定します。例：`30`秒。接続できなければ、**Max Retries**設定に従いリトライまたはエラーを返します。ネットワーク遅延や接続信頼性管理に有用です。 | `15` | +| **HTTP Pipelining** | 応答待ち前に送信可能なHTTPリクエストの最大数を指定します。 | `100` | +| **Connection Pool Size** | EMQXがSnowflakeに同時に維持可能な接続数を定義します。高負荷時に多くの同時リクエストを処理可能ですが、システムリソース消費も増加します。 | `8` | diff --git a/ja_JP/last_translation_commit b/ja_JP/last_translation_commit index 5c72160b9..5500dee5b 100644 --- a/ja_JP/last_translation_commit +++ b/ja_JP/last_translation_commit @@ -1 +1 @@ -43d988b7cf1970404b4eadf73ec981bd10a2ad06 +51b177b3bec144da00d5d5ce50ec2bc033f54249 diff --git a/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png b/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png new file mode 100644 index 000000000..119d9bdbd Binary files /dev/null and b/ja_JP/observability/opentelemetry/assets/e2e-dashboard-conf-en.png differ diff --git a/ja_JP/observability/opentelemetry/e2e-traces.md b/ja_JP/observability/opentelemetry/e2e-traces.md index 0f8030741..8416b9617 100644 --- a/ja_JP/observability/opentelemetry/e2e-traces.md +++ b/ja_JP/observability/opentelemetry/e2e-traces.md @@ -1,16 +1,16 @@ # OpenTelemetryベースのエンドツーエンドMQTTトレーシング -現代の分散システムにおいて、リクエストの流れを追跡しパフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることができます。 +現代の分散システムにおいて、リクエストの流れを追跡しパフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることを可能にします。 -EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信を明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステム信頼性の向上にも役立ちます。 +EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信を明確にトレース可能です。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステムの信頼性向上にも寄与します。 -本ページでは、MQTTメッセージのフローを包括的に可視化するために、EMQXでエンドツーエンドトレーシング機能を有効化する方法を詳しく解説します。 +本ページでは、EMQXでエンドツーエンドトレーシング機能を有効化し、MQTTメッセージフローの包括的な可視化を実現するための詳細な手順を解説します。 -## OpenTelemetry Collectorのセットアップ +## OpenTelemetryコレクターのセットアップ -設定の詳細については、[OpenTelemetry Collectorのセットアップ](./traces.md#setting-up-opentelemetry-collector)を参照してください。 +設定の詳細については、[OpenTelemetryコレクターのセットアップ](./traces.md#setting-up-opentelemetry-collector)を参照してください。 -## EMQXでエンドツーエンドトレーシングを有効化する +## EMQXでのエンドツーエンドトレーシングの有効化 ::: tip @@ -18,77 +18,99 @@ EMQXはバージョン5.8.3以降、MQTTプロトコルに特化したOpenTeleme ::: -このセクションでは、EMQXでOpenTelemetryベースのエンドツーエンドトレーシングを有効化する手順と、マルチノード環境でのMQTT分散トレーシング機能のデモを紹介します。 +このセクションでは、EMQXでOpenTelemetryベースのエンドツーエンドトレーシングを有効化する方法を案内し、マルチノード環境でのMQTT分散トレーシング機能を紹介します。 ### ダッシュボードからエンドツーエンドトレーシングを設定する -1. ダッシュボードの左メニューから **Management** -> **Monitoring** をクリックします。 -2. Monitoringページで **Integration** タブを選択します。 -3. 以下の設定を行います： - - **Monitoring platform**: `OpenTelemetry` を選択します。 - - **Feature Selection**: `Traces` を選択します。 - - **Endpoint**: トレースデータのエクスポート先アドレスを設定します。デフォルトは `http://localhost:4317` です。 - - **Enable TLS**: 必要に応じてTLS暗号化を有効にします。通常、本番環境のセキュリティ要件に合わせて設定します。 - - **Trace Mode**: `End-to-End` を選択し、エンドツーエンドトレーシング機能を有効化します。 - - **Cluster Identifier**: span属性に追加するプロパティ値を設定し、どのEMQXクラスターからのデータかを識別できるようにします。プロパティキーは `cluster.id` です。通常はシンプルで識別しやすい名前やクラスター名を設定します。デフォルトは `emqxcl` です。 - - **Traces Export Interval**: トレースデータのエクスポート間隔を秒単位で設定します。デフォルトは `5` 秒です。 - - **Max Queue Size**: トレースデータキューの最大サイズを設定します。デフォルトは `2048` エントリです。 +1. ダッシュボードの左メニューから **Management** -> **Monitoring** をクリックします。 -4. 必要に応じて **Trace Advanced Configuration** をクリックし、詳細設定を行います。 +2. Monitoringページの **Integration** タブを選択します。 - - **Trace Configuration**: クライアント接続やメッセージ送受信、ルールエンジンの実行など、特定イベントのトレース有無を設定できます。 - - **Follow Traceparent**: `traceparent` を追跡するかどうかを設定します。`true` に設定すると、EMQXはクライアントから送信された `User-Property` 内の `traceparent` 識別子を取得し、エンドツーエンドトレーシングに紐付けます。`false` の場合は新規トレースを生成します。デフォルトは `true` です。 - - **Client ID White List**: トレース対象とするクライアント接続やメッセージを制限するホワイトリストを設定できます。不要なトレースを避け、システムリソースの消費を抑制できます。 - - **Topic White List**: トピックのホワイトリストを設定し、マッチするトピックのみをトレース対象とします。クライアントホワイトリストと同様にトレース範囲の制御に役立ちます。 +3. 以下の設定を行います： + - **Monitoring platform**：`OpenTelemetry` を選択します。 - 設定後、**Confirm** をクリックして設定を保存しウィンドウを閉じます。 + - **Feature Selection**：`Traces` を選択します。 -5. **Save Changes** をクリックして設定を保存します。 + - **Endpoint**：トレースデータのエクスポート先アドレスを設定します。デフォルトは `http://localhost:4317` です。 -OpenTelemetryエンドツーエンドトレーシング ダッシュボード設定画面 + - **Headers**：トレースエクスポートリクエストにカスタムHTTPヘッダーを追加します。OpenTelemetryコレクターが認証やAPIキー、トークンなどのカスタムヘッダーを必要とする場合に有効です。各ヘッダーはキーと値のペアで指定してください。 -### 設定ファイルからエンドツーエンドトレーシングを設定する + OpenTelemetryコレクターがBasic認証を使用する場合は、`authorization` ヘッダーを以下の形式で追加する必要があります： -EMQXがローカルで稼働している前提で、`cluster.hocon` ファイルに以下の設定を追加します。 + ``` + Key: authorization + Value: Basic dXNlcjpwYXNzd29yZA== + ``` + + この設定により、HTTPベースの認証を強制するコレクターとの互換性が向上します。 + + - **Enable TLS**：必要に応じてTLS暗号化を有効化します。通常は本番環境のセキュリティ要件に応じて設定します。 + + - **Trace Mode**：`End-to-End` を選択し、エンドツーエンドトレーシング機能を有効にします。 + + - **Cluster Identifier**：スパン属性にクラスタ識別用のプロパティ値を追加します。プロパティキーは `cluster.id` です。通常はシンプルで識別しやすい名前やクラスター名を設定し、EMQXクラスター間の区別に利用します。デフォルトは `emqxcl` です。 + + - **Traces Export Interval**：トレースデータのエクスポート間隔を秒単位で設定します。デフォルトは `5` 秒です。 + + - **Max Queue Size**：トレースデータのキューの最大サイズを設定します。デフォルトは `2048` エントリです。 + +4. 必要に応じて **Trace Advanced Configuration** をクリックし、詳細設定を行います。 -設定オプションの詳細は、[EMQXダッシュボード監視統合のOpenTelemetry項目](http://localhost:18083/#/monitoring/integration)を参照してください。 + - **Trace Configuration**：クライアント接続、メッセージ送受信、ルールエンジン実行など、特定のイベントをトレースするかどうかの追加オプションを設定します。 + - **Follow Traceparent**：`traceparent` を追従するかどうかを設定します。`true` に設定すると、EMQXはクライアントから送信された `User-Property` 内の `traceparent` 識別子を取得し、エンドツーエンドトレーシングに紐付けます。`false` の場合は新たにトレースを生成します。デフォルトは `true` です。 + - **Client ID White List**：トレース対象とするクライアント接続やメッセージを制限するホワイトリストを設定します。不要なトレースを避け、システムリソースの消費を抑制できます。 + - **Topic White List**：トピックのホワイトリストを設定し、マッチするトピックのみをトレース対象にします。クライアントホワイトリストと同様にトレース範囲を制御可能です。 + + 設定保存後、**Confirm** をクリックしてウィンドウを閉じます。 + +5. 最後に **Save Changes** をクリックして設定を保存します。 + +Otel-E2E-Trace-dashboard-page + +### 設定ファイルでエンドツーエンドトレーシングを設定する + +EMQXがローカルで稼働している場合、`cluster.hocon` ファイルに以下の設定を追加します。 + +設定オプションの詳細は、[EMQXダッシュボード監視統合](http://localhost:18083/#/monitoring/integration)のOpenTelemetryセクションを参照してください。 ```bash opentelemetry { - exporter { endpoint = "http://localhost:4317" } + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = ""Basic dXNlcjpwYXNzd29yZA==" + } + } traces { - enable = true - # エンドツーエンドトレーシングモード - trace_mode = e2e - # エンドツーエンドトレーシングオプション - e2e_tracing_options { - ## クライアント接続/切断イベントをトレース - client_connect_disconnect = true - ## クライアントのサブスクライブ/アンインサブスクライブイベントをトレース - client_subscribe_unsubscribe = true - ## クライアントのメッセージングイベントをトレース - client_messaging = true - ## ルールエンジンの実行をトレース - trace_rule_engine = true - ## クライアントIDホワイトリストの最大長 - clientid_match_rules_max = 30 - ## トピックフィルターホワイトリストの最大長 - topic_match_rules_max = 30 - ## クラスター識別子 - cluster_identifier = emqxcl - ## メッセージトレースレベル（QoS） - msg_trace_level = 2 - ## ホワイトリスト外イベントのサンプリング率 - ## 注：トレースが有効な場合のみサンプリングが適用されます - sample_ratio = "100%" - ## traceparentの追跡 - ## クライアントから渡された`traceparent`をエンドツーエンドトレーシングで追跡するか - follow_traceparent + enable = true + # エンドツーエンドトレーシングモード + trace_mode = e2e + # エンドツーエンドトレーシングオプション + e2e_tracing_options { + ## クライアント接続/切断イベントをトレース + client_connect_disconnect = true + ## クライアントメッセージングイベントをトレース + client_messaging = true + ## クライアントサブスクライブ/アンインサブスクライブイベントをトレース + client_subscribe_unsubscribe = true + ## クライアントIDホワイトリストの最大長 + clientid_match_rules_max = 30 + ## トピックフィルタホワイトリストの最大長 + topic_match_rules_max = 30 + ## クラスター識別子 + cluster_identifier = emqxcl + ## メッセージトレースレベル（QoS） + msg_trace_level = 2 + ## ホワイトリスト外イベントのサンプリング率 + ## 注意：トレース有効時のみサンプリング適用 + sample_ratio = "100%" + ## traceparentを追従するか + ## クライアントから渡された`traceparent`をエンドツーエンドトレーシングで追従するかどうか + follow_traceparent } } max_queue_size = 50000 scheduled_delay = 1000 - } } ``` @@ -112,7 +134,7 @@ opentelemetry { 3. 約5秒後（EMQXのトレースデータエクスポートのデフォルト間隔）、[http://localhost:16686](http://localhost:16686/) のJaeger WEB UIにアクセスし、トレースデータを確認します。 - `emqx` サービスを選択し、**Find Traces** をクリックします。`emqx` サービスがすぐに表示されない場合は、少し待ってページを更新してください。クライアント接続およびサブスクライブイベントのトレースが確認できます： + `emqx` サービスを選択し、**Find Traces** をクリックします。`emqx` サービスがすぐに表示されない場合は、少し待ってページを更新してください。クライアント接続やサブスクライブイベントのトレースが表示されます： ![Jaeger-WEB-UI-e2e-Client-Events](./assets/e2e-client-events.png) @@ -124,34 +146,34 @@ opentelemetry { 5. 少し待つと、Jaeger WEB UIでMQTTメッセージの詳細なトレースが確認できます。 - トレースをクリックすると、詳細なspan情報とトレースタイムラインが表示されます。サブスクライバー数、ノード間のメッセージルーティング、QoSレベル、`msg_trace_level` 設定により、MQTTメッセージのトレースに含まれるspan数は異なります。 + トレースをクリックすると、スパンの詳細情報やトレースタイムラインが表示されます。サブスクライバー数、クロスノードのメッセージルーティング、QoSレベル、`msg_trace_level` の設定によって、MQTTメッセージトレースに含まれるスパン数は異なります。 - 以下は、2クライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信、`msg_trace_level` が2に設定されている場合のトレースタイムラインとspan情報の例です。 + 以下は、2つのクライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2のメッセージを送信、`msg_trace_level` が2に設定されている場合の例です。 - 特に、クライアント `mqttx_9137a6bb` がパブリッシャーとは異なるEMQXノードに接続しているため、ノード間の送信を表す2つの追加span（`message.forward` と `message.handle_forward`）が表示されています。 + 特に、クライアント `mqttx_9137a6bb` がパブリッシャーとは異なるEMQXノードに接続しているため、クロスノード伝送を表す2つの追加スパン（`message.forward` と `message.handle_forward`）が存在します。 ![Jaeger-WEB-UI-e2e-Message](./assets/e2e-message.png) - また、メッセージやイベントがルールエンジンの実行をトリガーする場合、ルールエンジンのトラッキングオプションが有効であれば、ルールおよびアクションの実行トラッキング情報も取得可能です。 + また、メッセージやイベントがルールエンジンの実行をトリガーする場合、ルールエンジントラッキングオプションを有効にすると、ルールおよびアクションの実行トラッキング情報も取得可能です。 ![Jaeger-WEB-UI-e2e-With-Rule-Engine](./assets/e2e-with-rule-engine.png) ::: tip - ルールエンジンの実行を含むエンドツーエンドトレーシング機能は、EMQXバージョン5.9.0以降でサポートされています。 + ルールエンジン実行を含むエンドツーエンドトレーシング機能は、EMQXバージョン5.9.0以降でのみサポートされています。 ::: ::: warning 重要なお知らせ - この機能は慎重に有効化してください。メッセージやイベントが複数のルールやアクションをトリガーすると、単一のトレースで大量のspanが生成され、システム負荷が増加します。 + この機能は慎重に有効化してください。メッセージやイベントが複数のルールやアクションをトリガーすると、単一のトレースで大量のスパンが生成され、システム負荷が増加します。 メッセージ量やルール・アクション数に応じて適切なサンプリング率を見積もってください。 ::: -## トレースspanのオーバーロード管理 +## トレーススパンの過負荷管理 -EMQXはトレースspanを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレースspanプロセッサにはオーバーロード保護機能があり、最大蓄積数（デフォルト2048span）を超えると新規spanは破棄されます。以下の設定でこの制限を調整可能です。 +EMQXはトレーススパンを蓄積し、定期的にバッチでエクスポートします。エクスポート間隔は `opentelemetry.trace.scheduled_delay` パラメータで制御され、デフォルトは5秒です。バッチトレーススパンプロセッサには過負荷保護機能があり、スパンの蓄積は上限まで許容されます。デフォルトの上限は2048スパンです。この上限は以下の設定で調整可能です。 ```yaml opentelemetry { @@ -162,14 +184,14 @@ opentelemetry { } ``` -`max_queue_size` の上限に達すると、現在のキューがエクスポートされるまで新規トレースspanは破棄されます。 +`max_queue_size` の上限に達すると、新たなトレーススパンは現在のキューがエクスポートされるまで破棄されます。 ::: tip 補足 -トレース対象メッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、オーバーロード保護により多くのspanが破棄され、エクスポートされるspanはごく一部になる可能性があります。 +トレース対象のメッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、過負荷保護により多くのスパンが破棄され、エクスポートされるスパンはごく一部になる可能性があります。 -エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増やし、`scheduled_delay` を短縮してspanのエクスポート頻度を上げることを検討してください。これによりオーバーロード保護によるspanの損失を抑制できます。 +エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて `max_queue_size` を増加させ、`scheduled_delay` を短縮してスパンのエクスポート頻度を上げることを検討してください。これにより過負荷保護によるスパンの損失を軽減できます。 -**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソース消費を増加させるため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切に設定してください。** +**ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソースの消費増加を招くため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切な設定を行ってください。** ::: diff --git a/ja_JP/observability/opentelemetry/logs.md b/ja_JP/observability/opentelemetry/logs.md index c38f0624c..3004bd499 100644 --- a/ja_JP/observability/opentelemetry/logs.md +++ b/ja_JP/observability/opentelemetry/logs.md @@ -1,11 +1,12 @@ -# OpenTelemetryを使ったログ管理の統合 -ファイルログと同様に、OpenTelemetryログは重要なイベント、ステータス情報、エラーメッセージを記録し、開発者や運用チームがアプリケーションの動作を理解しトラブルシューティングを行うのに役立ちます。ただし、OpenTelemetryログは標準化されたログフォーマットを採用しているため、ログの解析や分析、処理が容易です。さらに、Trace ID、タグ、属性などの豊富なコンテキスト情報をログに付加できる点も特徴です。 +# OpenTelemetryによるログ管理の統合 -本ページでは、EMQXとOpenTelemetryログハンドラーを統合して高度なログ管理を実現する方法を詳しく解説します。OpenTelemetry Collectorのセットアップ、EMQXでのOpenTelemetryログハンドラーの設定およびログのエクスポート方法、ログ過負荷の管理について説明します。この統合により、EMQXのログイベントを[OpenTelemetryログデータモデル](https://opentelemetry.io/docs/specs/otel/logs/data-model/)に準拠した形式で出力し、設定したOpenTelemetry Collectorやバックエンドにエクスポートできるため、監視やデバッグの効率が向上します。 +ファイルログと同様に、OpenTelemetryログは重要なイベント、ステータス情報、エラーメッセージを記録し、開発者や運用チームがアプリケーションの挙動を理解しトラブルシューティングを行うのに役立ちます。ただし、OpenTelemetryログは標準化されたログフォーマットを採用しているため、ログの解析や分析、処理が容易です。さらに、OpenTelemetryログはTrace ID、タグ、属性などの豊富なコンテキスト情報をレコードに追加することをサポートしています。 + +本ページでは、EMQXにOpenTelemetryログハンドラーを統合して高度なログ管理を実現するための包括的なガイドを提供します。OpenTelemetry Collectorのセットアップ、EMQXでのOpenTelemetryログハンドラーの設定およびログのエクスポート方法、ログ過負荷の管理について説明します。この統合により、EMQXのログイベントを[OpenTelemetryログデータモデル](https://opentelemetry.io/docs/specs/otel/logs/data-model/)に準拠した形式でフォーマットし、設定済みのOpenTelemetry Collectorやバックエンドシステムにエクスポートできるようになり、監視やデバッグ機能が向上します。 ## OpenTelemetry Collectorのセットアップ -EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry CollectorおよびOpenTelemetry対応のログ収集システムをデプロイし設定する必要があります。本ガイドでは、[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)のデプロイ方法と、debugエクスポーターを使ってログを`stdout`にリダイレクトする設定手順を説明します。 +EMQXのOpenTelemetryログ機能を有効にする前に、OpenTelemetry CollectorおよびOpenTelemetry対応のログ収集システムをデプロイして設定する必要があります。本ガイドでは、[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)のデプロイ方法と、デバッグエクスポーターを使用してログを`stdout`にリダイレクトする設定方法を説明します。 1. `otel-logs-collector-config.yaml`という名前でOpenTelemetry Collectorの設定ファイルを作成します。 @@ -60,23 +61,27 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお 4. 起動後、OpenTelemetry Collectorは[http://localhost:4317](http://localhost:4317/)でアクセス可能になります。 +## EMQXでのOpenTelemetryログハンドラーの有効化 -## EMQXでOpenTelemetryログハンドラーを有効化 - -1. EMQXの`cluster.hocon`ファイルに以下の設定を追加します（EMQXがローカルで動作している想定です）。 +1. EMQXがローカルで動作していることを前提に、`cluster.hocon`ファイルに以下の設定を追加します。 ```bash opentelemetry { - exporter {endpoint = "http://localhost:4317"} + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = ""Basic dXNlcjpwYXNzd29yZA==" + } + } logs {enable = true, level = warning} } ``` - または、ダッシュボードの **Management** -> **Monitoring** にある **Integration** タブからOpenTelemetryログ統合を設定することも可能です。 + また、ダッシュボードの **Management** -> **Monitoring** に移動し、ページ内の **Integration** タブからOpenTelemetryログ統合を設定することも可能です。 - ::: tip 補足 + ::: tip 注意事項 - `opentelemetry.logs.level`の設定は、[EMQXログハンドラー](../../observability/log.md)で設定されたデフォルトのログレベルにより上書きされます。例えば、OpenTelemetryのログレベルが`info`でも、EMQXのコンソールログレベルが`error`の場合は、`error`以上のレベルのイベントのみがエクスポートされます。 + `opentelemetry.logs.level`の設定は、[EMQXログハンドラー](../../observability/log.md)で設定されたデフォルトのログレベルにより上書きされます。たとえば、OpenTelemetryのログレベルが`info`でも、EMQXのコンソールログレベルが`error`の場合、`error`以上のレベルのイベントのみがエクスポートされます。 ::: @@ -86,15 +91,13 @@ EMQXのOpenTelemetryログを有効にする前に、OpenTelemetry Collectorお Otel-logs-HTTP-bridge-example -4. 数秒以内（デフォルトは約1秒）に、Otel CollectorがHTTPブリッジ接続失敗などのEMQXログイベントを受信していることを確認できます。 +4. しばらくすると（デフォルトで約1秒後）、OpenTelemetry CollectorにHTTPブリッジ接続失敗などのEMQXログイベントが表示されます。 ![Otel-collector-logs-debug-output](./assets/otel-collector-logs-debug-output.png) ## ログ過負荷の管理 -EMQXはログイベントを蓄積し、一定間隔でバッチ処理としてエクスポートします。 -このエクスポートの頻度は`opentelemetry.logs.scheduled_delay`パラメータで制御され、デフォルトは1秒です。 -バッチ処理のログハンドラーは過負荷保護機構を備えており、蓄積できるイベント数に上限を設けています。デフォルトの上限は2048件です。以下の設定でこの上限を変更できます。 +EMQXはログイベントを蓄積し、定期的にバッチでエクスポートします。このエクスポート頻度は`opentelemetry.logs.scheduled_delay`パラメータで制御され、デフォルトは1秒です。バッチングログハンドラーには過負荷保護機構が組み込まれており、蓄積可能なイベント数の上限（デフォルト2048）を超えると新しいログイベントは破棄されます。この上限は以下の設定で変更可能です。 ```bash opentelemetry { @@ -102,11 +105,10 @@ opentelemetry { } ``` -`max_queue_size`の上限に達すると、新しいログイベントは現在のキューがエクスポートされるまで破棄されます。 +`max_queue_size`の制限に達すると、現在のキューがエクスポートされるまで新しいログイベントは破棄されます。 -::: tip 補足 +::: tip 注意事項 -OpenTelemetryログの過負荷保護は、デフォルトの[EMQXログハンドラー](../log.md)の過負荷保護とは独立して動作します。 -そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄される一方、EMQXのデフォルトログハンドラーでは記録される場合や、その逆もあり得ます。 +OpenTelemetryログの過負荷保護は、デフォルトの[EMQXログハンドラー](../log.md)の過負荷保護とは独立して動作します。そのため、設定によっては同じログイベントがOpenTelemetryハンドラーで破棄される一方、デフォルトのEMQXログハンドラーでは記録される場合や、その逆もあり得ます。 ::: diff --git a/ja_JP/observability/opentelemetry/metrics.md b/ja_JP/observability/opentelemetry/metrics.md index 233044f34..f26fc91bd 100644 --- a/ja_JP/observability/opentelemetry/metrics.md +++ b/ja_JP/observability/opentelemetry/metrics.md @@ -1,14 +1,14 @@ # OpenTelemetryを統合してメトリクスを表示する -EMQXは、gRPC OTELプロトコルを介してメトリクスを直接OpenTelemetry Collectorにプッシュする機能を標準でサポートしています。Collectorはデータを任意のバックエンドにルーティング、フィルタリング、変換し、保存および可視化が可能です。 +EMQXは、gRPC OTELプロトコルを介してメトリクスをOpenTelemetry Collectorに直接プッシュする機能を内蔵しています。Collectorはその後、データを任意のバックエンドにルーティング、フィルタリング、変換して保存および可視化に利用できます。 -本ページでは、EMQXとOpenTelemetryの統合方法をダッシュボードを通じて紹介し、[Prometheus](../../observability/prometheus.md)でEMQXのメトリクスを表示する方法を説明します。 +このページでは、Dashboardを通じてEMQXとOpenTelemetryを統合し、[Prometheus](../../observability/prometheus.md)でEMQXのメトリクスを表示する方法を紹介します。 ## 前提条件 -OpenTelemetryとの統合を行う前に、OpenTelemetryとPrometheusをデプロイおよび設定しておく必要があります。 +OpenTelemetryとの統合を行う前に、OpenTelemetryおよびPrometheusをデプロイし、設定する必要があります。 - [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/getting-started)をデプロイします。 -- CollectorのgRPC受信ポート（デフォルトは4317）とPrometheusメトリクスエクスポートポート（8889）を設定します。 +- CollectorのgRPC受信ポート（デフォルトは4317）およびPrometheusメトリクスエクスポートポート（8889）を設定します。 ```yaml # otel-collector-config.yaml @@ -33,7 +33,7 @@ service: ``` - [Prometheus](https://prometheus.io/docs/prometheus/latest/installation)をデプロイします。 -- Prometheusを設定し、Collectorが収集したメトリクスをスクレイプするようにします。 +- Prometheusを設定して、Collectorが収集したメトリクスをスクレイプします。 ```yaml # prometheus.yaml @@ -47,13 +47,18 @@ scrape_configs: ## EMQXでOpenTelemetryメトリクスを有効化する -EMQXのOpenTelemetryメトリクス機能との統合は、EMQXダッシュボードまたは設定ファイルで行えます。ダッシュボードでは、左側のナビゲーションメニューから **Management** -> **Monitoring** をクリックし、**Integration** タブでメトリクスの設定を行います。 +EMQX Dashboardまたは設定ファイルを使用して、OpenTelemetryメトリクス機能との統合を設定できます。EMQX Dashboardでは、左側のナビゲーションメニューから **Management** -> **Monitoring** をクリックし、**Integration** タブを選択してメトリクスの設定を行います。 EMQXがローカルで動作している場合、以下の設定をEMQXの `cluster.hocon` ファイルに追加してください。 ```bash opentelemetry { - exporter { endpoint = "http://localhost:4317" } + exporter { + endpoint = "http://localhost:4317" + headers { + authorization = "Basic dXNlcjpwYXNzd29yZA==" + } + } metrics { interval = "10s" } @@ -62,5 +67,5 @@ opentelemetry { ## PrometheusでEMQXメトリクスを可視化する -EMQXのメトリクスは、PrometheusのWebコンソール（http://otel-collector:9090）で確認できます。 +EMQXのメトリクスはPrometheusのWebコンソール（http://otel-collector:9090）で確認できます。 ![OpenTelemetry-Prometheus](./assets/opentelemetry-prometheus.png) diff --git a/ja_JP/observability/opentelemetry/opentelemetry.md b/ja_JP/observability/opentelemetry/opentelemetry.md index e3c32ffb7..5d4e47166 100644 --- a/ja_JP/observability/opentelemetry/opentelemetry.md +++ b/ja_JP/observability/opentelemetry/opentelemetry.md @@ -1,13 +1,17 @@ # OpenTelemetryとの統合 -[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/)は、トレース、メトリクス、ログなどのテレメトリーデータを生成・管理するためのオブザーバビリティフレームワークおよびツールキットです。重要な点として、OpenTelemetryはベンダーやツールに依存しないため、JaegerやPrometheusなどのオープンソースツールから商用製品まで、幅広いオブザーバビリティバックエンドと連携可能です。 +[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/)は、トレース、メトリクス、ログなどのテレメトリデータを生成および管理するためのオブザーバビリティフレームワークおよびツールキットです。重要な点として、OpenTelemetryはベンダーやツールに依存しないため、JaegerやPrometheusなどのオープンソースツールから商用製品まで、幅広いオブザーバビリティバックエンドと連携可能です。 -EMQXはgRPC OTELプロトコルを介してOpenTelemetry Collectorへテレメトリーデータを直接プッシュすることをサポートしており、Collectorを通じてデータの転送、フィルタリング、変換を行い、Jaegerや[Prometheus](../../observability/prometheus.md)などの任意のバックエンドに統合して保存・可視化できます。OpenTelemetryとの統合により、EMQXのメトリクス収集、メッセージパブリッシュの分散トレーシング、ログの統合収集およびコンテキスト関連付けが最適化されます。この統合は、EMQXの可視化監視やアラート通知の実現、異なるシステムやサービス間のメッセージフローの追跡に役立ちます。これにより、継続的なパフォーマンス最適化、迅速な問題特定、システム監視が可能となります。 +EMQXは、gRPC OTELプロトコルを介してOpenTelemetry Collectorにテレメトリデータを直接プッシュすることをサポートしており、その後Collectorを通じてデータの転送、フィルタリング、変換を行い、Jaegerや[Prometheus](../../observability/prometheus.md)などの任意のバックエンドに統合して保存および可視化できます。OpenTelemetryとの統合により、EMQXのメトリクス収集、メッセージパブリッシュの分散トレーシング、ログの統合収集およびコンテキスト関連付けが最適化されます。この統合は、EMQXの可視化監視やアラート通知の実現、異なるシステムやサービス間のメッセージフローの追跡に役立ちます。これにより、継続的なパフォーマンス最適化、迅速な問題特定、システム監視が可能となります。 emqx-opentelemetry -本セクションでは、EMQXがOpenTelemetry Collectorとテレメトリーデータを統合し、以下のオブザーバビリティ情報に対して完全な組み込みOpenTelemetryサポートを実現する方法を紹介します。 +本セクションでは、EMQXがOpenTelemetry Collectorとテレメトリデータを統合し、以下のオブザーバビリティ情報に対して完全な組み込みOpenTelemetryサポートを実現する方法を紹介します。 - [メトリクス](./metrics.md) - [トレース](./traces.md) - [ログ](./logs.md) + +さらに、EMQXバージョン5.8.3以降では、OpenTelemetryに基づくエンドツーエンドトレーシングもサポートしています。 + +- [エンドツーエンドトレース](./e2e-traces.md) diff --git a/ja_JP/support/technical-support.md b/ja_JP/support/technical-support.md index 4dc228741..bc18838d2 100644 --- a/ja_JP/support/technical-support.md +++ b/ja_JP/support/technical-support.md @@ -1,23 +1,23 @@ --- title: EMQX テクニカルサポート -description: EMQX Enterprise向けの専門的なテクニカルサポートをご提供し、堅牢なソリューションとプロフェッショナルな支援でIoTミドルウェアプラットフォームの最適化を支援します。 +description: EMQX Enterprise の専門的なテクニカルサポートをご提供し、堅牢なソリューションとプロフェッショナルな支援で IoT ミドルウェアプラットフォームの最適化をサポートします。 --- # EMQX テクニカルサポート -EMQは、世界をリードするオープンソースIoTデータインフラストラクチャのソフトウェアプロバイダーです。エッジからクラウド、マルチクラウドに至るまで、リアルタイムIoTデータの接続、移動、処理、分析を一元的に実現するクラウドネイティブ製品を通じて、将来にわたって対応可能なIoTアプリケーションの実現を支援しています。 +EMQ は、世界をリードするオープンソース IoT データインフラストラクチャのソフトウェアプロバイダーです。エッジからクラウド、マルチクラウドに至るまで、リアルタイムの IoT データを接続、移動、処理、分析するワンストップのクラウドネイティブ製品を通じて、将来を見据えた IoT アプリケーションの実現を支援しています。 -当社のコア製品であるEMQXは、世界で最もスケーラブルかつ信頼性の高いオープンソースMQTTメッセージングプラットフォームであり、1クラスターあたり1億の同時IoTデバイス接続をサポートしつつ、毎秒100万メッセージのスループットとサブミリ秒のレイテンシを維持します。2万社以上の企業ユーザーが利用し、1億台以上のIoTデバイスを接続、HPE、VMware、Verifone、SAIC Volkswagen、Ericssonなどの著名ブランドを含む400社以上のミッションクリティカルなIoTシナリオで信頼されています。 +当社のコア製品である EMQX は、世界で最もスケーラブルかつ信頼性の高いオープンソース MQTT メッセージングプラットフォームであり、1 クラスターあたり 1 億台の同時 IoT デバイス接続をサポートし、毎秒 100 万メッセージのスループットとサブミリ秒のレイテンシを維持します。20,000 社以上の企業ユーザーに利用され、1 億台以上の IoT デバイスを接続しており、HPE、VMware、Verifone、SAIC Volkswagen、Ericsson などの著名ブランドを含む 400 社以上のミッションクリティカルな IoT シナリオで信頼されています。 -EMQのグローバルR&Dセンターはストックホルムに位置し、アメリカ大陸、ヨーロッパ、アジア太平洋地域に10以上のオフィスを展開しています。 +EMQ のグローバル R&D センターはストックホルムにあり、アメリカ大陸、ヨーロッパ、アジア太平洋地域に 10 以上のオフィスを展開しています。 -EMQX製品や当社のIoTソリューションに関するご質問がございましたら、以下までお気軽にお問い合わせください。 +EMQX 製品や IoT ソリューションに関するご質問がございましたら、以下までお気軽にお問い合わせください。 **EMQ** **メール:** [contact@emqx.io](mailto:contact@emqx.io) -**製品フィードバック:** [EMQX Support Portal](https://www.emqx.com/en/support) +**製品フィードバック:** [EMQX サポートポータル](https://www.emqx.com/en/support) **営業:** [sales@emqx.io](mailto:sales@emqx.io) @@ -27,37 +27,36 @@ EMQX製品や当社のIoTソリューションに関するご質問がござい **所在地:** -- 本社： 中国 浙江省 杭州市 餘杭区 龍源路88号 3号棟 A301 -- グローバルR&Dセンター： スウェーデン ストックホルム Mazarinvägen 36 Sköndal -- ヨーロッパオフィス： ドイツ フランクフルト Eschborner Landstraße 42-50 Haus B, 60489 Frankfurt(M) -- 米国オフィス： 1300 El Camino Real, Suite 100, Menlo Park, CA 94025 +- 本社：中国 浙江省 杭州市 餘杭区 龍源路88号 3号棟 A301 +- グローバル R&D センター：スウェーデン ストックホルム Mazarinvägen 36 Sköndal +- 欧州オフィス：ドイツ フランクフルト Eschborner Landstraße 42-50 Haus B, 60489 Frankfurt(M) +- 米国オフィス：1300 El Camino Real, Suite 100, Menlo Park, CA 94025 -EMQXサービスチームは、専門的なサポートを提供いたします： +EMQX サービスチームは、専門的なサポートをご提供いたします。 -- IoTソリューションの設計、デプロイメント、カスタマイズに関する専門的なサポートについては、[EMQXサービスチーム](https://www.emqx.com/en/contact?product=emqx)までご連絡ください。 -- 提供している商用サポートの詳細は、[EMQX Support Portal](https://www.emqx.com/en/support)をご覧ください。 +- IoT ソリューションの設計、デプロイ、カスタマイズに関する専門的なサポートは、[EMQX サービスチーム](https://www.emqx.com/en/contact?product=emqx)までご連絡ください。 +- [EMQX サポートポータル](https://www.emqx.com/en/support)では、当社が提供する商用サポート内容をご確認いただけます。 **商用サポートレベル** | 機能 | スタンダード | プロフェッショナル | | -------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | -| サポート時間 | 平日9時～18時（5*8） | 24時間365日（7*24） | +| サポート時間 | 平日 9:00～18:00（5日間） | 24時間365日（7日間） | | メールサポート | support | support | | オンラインチャットサポート | support | support | | 電話ホットラインサポート | no support | support | | 対応時間 | 8時間以内 | 2時間以内 | | 重要バグ修正 | no support | support | -| サードパーティプラグインサポート | no support | support | +| サードパーティプラグイン対応 | no support | support | -EMQXの開発者およびユーザーの皆様は、EMQXフォーラムやSlackチャンネル、GitHubページに参加して質問や回答の共有、アイデアやベストプラクティスの交換が可能です： +EMQX の開発者およびユーザーの皆様は、EMQX フォーラムや Slack チャンネル、GitHub ページにて質問、回答、アイデアやベストプラクティスの共有が可能です。 -- [EMQXフォーラム](https://www.emqx.io/forum/)：EMQXに関する質問を投稿できます。 -- [Slack](https://slack-invite.emqx.io/)：世界中のEMQX開発者やユーザーとつながれます。 -- [GitHub](https://github.com/emqx/emqx)：EMQXのコード取得、問題報告、新機能リクエストが行えます。 +- [Slack](https://slack-invite.emqx.io/): 世界中の EMQX 開発者およびユーザーとつながれます。 +- [GitHub](https://github.com/emqx/emqx): EMQX のソースコードの閲覧、問題報告、新機能のリクエストが可能です。 -また、以下のSNSでも情報発信を行っています： +また、以下のチャネルでもご連絡いただけます。 -- [Twitter](https://twitter.com/EMQTech) +- [X](https://x.com/EMQTech) - [YouTube](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) - [LinkedIn](https://www.linkedin.com/company/emqtech) - [Discord](https://discord.com/invite/xYGf3fQnES)