次の方法で共有

postgresql_request プラグイン

  • [アーティクル]

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー

postgresql_request プラグインは、Azure PostgreSQL Server ネットワーク エンドポイントに SQL クエリを送信し、結果の最初の行セットを返します。 クエリで複数の行セットが返される場合がありますが、Kusto クエリの残りの部分で使用できるのは最初の行セットだけです。

このプラグインは、evaluate 演算子を使用して呼び出されます。

重要

postgresql_request プラグインは既定では無効です。 このプラグインを有効にするには、.enable plugin postgresql_request コマンドを実行します。 有効になっているプラグインを確認するには、.show plugin 管理コマンドを使用します。

構文

evaluatepostgresql_request ( ConnectionString , SqlQuery [, SqlParameters] ) [: OutputSchema]

構文規則について詳しく知る。

パラメーター

件名 タイプ Required 説明
ConnectionString string ✔️ PostgreSQL Server ネットワーク エンドポイントを指す接続文字列。 認証およびネットワーク エンドポイントの指定方法に関するセクションを参照してください。
SqlQuery string ✔️ SQL エンドポイントに対して実行されるクエリ。 1 つ以上の行セットを返す必要があります。 最初のセットのみが、クエリの残りの部分で使用できるようになります。
SqlParameters dynamic クエリと共にパラメーターとして渡すキーと値のペアを保持するプロパティ バッグ オブジェクト。
OutputSchema postgresql_request プラグイン出力の予想される列の名前と型。

構文: ( ColumnName : ColumnType [, ...] )

Note

  • OutputSchema を指定することを強くお勧めします。クラスター間クエリなど、それ以外の場合は機能しない可能性があるシナリオでプラグインを使用できるためです。 OutputSchema では、複数のクエリの最適化を有効にすることもできます。
  • SQL ネットワーク エンドポイントによって返される最初の行セットの実行時スキーマが、 OutputSchema スキーマと一致しない場合、エラーが発生します。

認証と権限承認

PostgreSQL Server ネットワーク エンドポイントを承認するには、接続文字列で承認情報を指定する必要があります。 サポートされている承認方法は、ユーザー名とパスワードを使用します。

コールアウト ポリシーの設定

プラグインは PostgreSQL データベースにコールアウトを行います。 クラスターの callout ポリシーターゲット PostgreSqlDbUri への型postgresqlの呼び出しが有効になっていることを確認します。

次の例は、PostgreSQL データベースのコールアウト ポリシーを定義する方法を示しています。 コールアウト ポリシーを特定のエンドポイント (my_endpoint1、my_endpoint2) に限定することをお勧めします。

[
  {
    "CalloutType": "postgresql",
    "CalloutUriRegex": "my_endpoint1\\.postgres\\.database\\.azure\\.com",
    "CanCall": true
  },
  {
    "CalloutType": "postgresql",
    "CalloutUriRegex": "my_endpoint2\\.postgres\\.database\\.azure\\.com",
    "CanCall": true
  }
]

次の例は、postgresql CalloutType の.alter callout policy コマンドを示しています。

.alter cluster policy callout @'[{"CalloutType": "postgresql", "CalloutUriRegex": "\\.postgresql\\.database\\.azure\\.com", "CanCall": true}]'

ユーザー名とパスワードの認証

postgresql_request プラグインでは、PostgreSQL サーバー エンドポイントに対するユーザー名とパスワードの認証のみがサポートされ、Microsoft Entra 認証と統合されません。

ユーザー名とパスワードは、次のパラメーターを使用して接続文字列の一部として提供されます。

User ID=...; Password=...;

警告

秘密情報や保護されている情報は、Kusto トレースから除外されるようにするため、接続文字列やクエリに対して難読化する必要があります。 詳細については、「難読化文字列リテラル」を参照してください。

暗号化とサーバー検証

セキュリティのために、 SslMode は PostgreSQL サーバー ネットワーク エンドポイントに接続するときに無条件に Required に設定されます。 その結果、サーバーは、有効な SSL/TLS サーバー証明書を使用して構成することが必要になります。

ネットワーク エンドポイントを指定する

接続文字列の一部として PostgreSQL ネットワーク エンドポイントを指定します。

構文：

Host= FQDN [Port = Port]

ここで:

  • FQDN は、そのエンドポイントの完全修飾ドメイン名です。
  • Port は、そのエンドポイントの TCP ポートです。

例

Azure PostgreSQL DB への SQL クエリ

次の例では、SQL クエリを Azure PostgreSQL データベースに送信します。 このクエリは、public."Table" からすべてのレコードを取得し、その結果を処理します。

Note

この例は、この方法でデータをフィルター処理またはプロジェクトするように推奨するためのものではありません。 SQL クエリは、可能な限り最小のデータセットを返すように構築する必要があります。

evaluate postgresql_request(
    'Host=contoso.postgres.database.azure.com; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select * from public."Table"') : (Id: int, Name: string)
| where Id > 0
| project Name

変更を加えた Azure PostgreSQL データベースへの SQL クエリ

次の例では、sql クエリを Azure PostgreSQL データベースに送信し、 public."Table"からすべてのレコードを取得しながら、別の datetime 列を追加し、結果を処理します。 これは、SQL クエリで使用される SQL パラメーター (@param0) を指定します。

evaluate postgresql_request(
    'Server=contoso.postgres.database.azure.com; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select *, @param0 as dt from public."Table"',
    dynamic({'param0': datetime(2020-01-01 16:47:26.7423305)})) : (Id: int, Name: string, dt: datetime)
| where Id > 0
| project Name

クエリ定義の出力スキーマを使用しない Azure PostgreSQL データベースへの SQL クエリ

次の例では、SQL クエリを出力スキーマなしで Azure PostgreSQL データベースに送信します。 スキーマが不明でない限り、クエリのパフォーマンスに影響を与える可能性があるため、これはお勧めしません

evaluate postgresql_request(
    'Host=contoso.postgres.database.azure.com; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select * from public."Table"')
| where Id > 0
| project Name