postgresql_request 外掛程式

發行項
11/23/2024

適用於： ✅Microsoft網狀架構✅Azure 數據總管

外掛程式 postgresql_request 會將 SQL 查詢傳送至 Azure PostgreSQL Server 網路端點，並傳回結果中的第一個數據列集。查詢可能會傳回一個以上的數據列集，但只有第一個數據列集可供 Kusto 查詢的其餘部分使用。

外掛程式是使用運算子叫 evaluate 用的。

重要

外掛程式 postgresql_request 預設為停用。若要啟用外掛程式，請 .enable plugin postgresql_request 執行命令。若要查看已啟用哪些外掛程式，請使用 .show plugin 管理命令。

語法

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

深入瞭解語法慣例。

參數

姓名	類型	必要	描述
ConnectionString	`string`	✔️	指向 PostgreSQL 伺服器端點的連接字串。請參閱驗證，以及如何指定網路端點。
SqlQuery	`string`	✔️	要針對 SQL 端點執行的查詢。必須傳回一或多個數據列集。只有第一組可供其餘查詢使用。
SqlParameters	`dynamic`		屬性包物件，保存索引鍵/值組，以作為參數與查詢一起傳遞。
OutputSchema			外掛程式輸出之預期 `postgresql_request` 數據行的名稱和類型。語法： `(` ColumnName `:` ColumnType [`,` ...]`)`

注意

強烈建議指定 OutputSchema，因為它可讓外掛程式用於若沒有外掛程式的情況下可能無法運作，例如跨叢集查詢。 OutputSchema 也可以啟用多個查詢優化。
如果 SQL 網路端點所傳回之第一個數據列集的運行時間架構不符合 OutputSchema 架構，就會引發錯誤。

驗證與授權

若要授權 PostgreSQL Server 網路端點，您必須在連接字串中指定授權資訊。支援的授權方法是透過使用者名稱和密碼。

設定註標原則

外掛程式會向 PostgreSQL 資料庫發出註標。請確定叢集的圖說原則會啟用目標 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
  }
]

下列範例顯示 .alter callout policy CalloutType 的postgresql命令：

.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 = 連接埠]

其中：

FQDN 是端點的完整功能變數名稱。
埠是連接點的 TCP 連接埠。

範例

對 Azure PostgreSQL DB 的 SQL 查詢

下列範例會將 SQL 查詢傳送至 Azure PostgreSQL 資料庫。它會從 public."Table"擷取所有記錄，然後處理結果。

注意

此範例不應以此方式作為篩選或專案數據的建議。應該建構 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

共用方式為