處理數據源路徑

發行項
05/15/2024

M 引擎會使用其 Kind 和 Path 的組合來識別數據源。在查詢評估期間遇到數據源時，M 引擎會嘗試尋找相符的認證。如果找不到認證，引擎會傳回特殊錯誤，導致 Power Query 中的認證提示。

Kind 值來自數據源種類定義。

Path 值衍生自數據源函式的必要參數。 選擇性參數不會納入數據源路徑標識碼。因此，與數據源種類相關聯的所有數據源函式都必須具有相同的參數。函式有特殊處理，其類型為的單一參數 Uri.Type。如需詳細資訊，請移至具有URI參數的函式。

您可以看到認證如何儲存在 Power BI Desktop 的 [數據源設定 ] 對話框中的範例。在此對話框中，Kind 是以圖示表示，而 Path 值會顯示為文字。

數據源設定認證的螢幕快照。

注意

如果您在開發期間變更數據源函式的必要參數，先前儲存的認證就無法再運作（因為路徑值不再相符）。每當變更資料源函式參數時，您應該刪除任何儲存的認證。如果找到不相容的認證，您可能會在運行時間收到錯誤。

數據源路徑格式

數據源的Path值衍生自數據源函式的必要參數。新增至函式的元數據，即可從路徑 DataSource.Path = false 中排除必要的參數。如需詳細資訊，請移至從數據源路徑排除必要的參數。

根據預設，您可以在 Power BI Desktop 的 [數據源設定] 對話框和認證提示中看到實際的字串值。如果數據源種類定義包含 Label 值，您將改為看到標籤。

例如，HelloWorldWithDocs 範例中的數據源函式具有下列簽章：

HelloWorldWithDocs.Contents = (message as text, optional count as number) as table => ...

函式具有類型的text單一必要參數（message），可用來計算數據源路徑。會忽略選擇性參數（count）。路徑會顯示如下：

認證提示

包含路徑之認證提示的螢幕快照。

數據源設定UI

數據源設定UI的螢幕快照。

定義標籤值時，不會顯示資料來源路徑值：

已定義標籤的數據源設定螢幕快照。

注意

目前，如果您的函式具有必要的參數，建議您不要包含數據源的標籤，因為使用者無法區分他們輸入的不同認證。我們希望在未來改善這一點（也就是說，允許數據連接器顯示自己的自定義數據源路徑）。

從數據源路徑排除必要的參數

如果您想要需要函式參數，但不能包含在數據源路徑中，您可以將新增 DataSource.Path = false 至函式檔元數據。這個屬性可以新增至函式的一或多個參數。此欄位會從數據源路徑中移除值（這表示它不再傳遞至您的 TestConnection 函式），因此它只應該用於識別數據源所需的參數，或區分用戶認證。

例如，HelloWorldWithDocs 範例中的連接器需要不同值的認證message。新增 DataSource.Path = false 至 message 參數會從數據源路徑計算中移除它，有效地使連接器成為「單一」。對的所有呼叫 HelloWorldWithDocs.Contents 都會視為相同的數據源，而且使用者只會提供認證一次。

HelloWorldType = type function (
    message as (type text meta [
        DataSource.Path = false,
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

具有 URI 參數的函式

由於具有 URI 型標識符的數據源非常常見，所以處理 URI 型數據源路徑時，Power Query UI 中有特殊處理。遇到 URI 型資料源時，認證對話方塊會提供下拉式清單，讓使用者選取基底路徑，而不是完整路徑（以及介於之間的所有路徑）。

顯示認證套用之設定路徑的認證對話框螢幕快照。

如同 Uri.Type M 語言中的刻字型別，而不是基本類型，您必須使用 Value.ReplaceType 函式來指出應該將文字參數視為 URI。

shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.type) as any);

共用方式為