データ ソース パスの処理

M エンジンは、その Kind と Path の組み合わせを使用して、データ ソースを識別します。 クエリ評価中にデータ ソースが検出されると、M エンジンは一致する資格情報を見つけようとします。 資格情報が見つからない場合、エンジンは特別なエラーを返し、Power Query で資格情報プロンプトが表示されます。

Kind 値は、Data Source Kind 定義から取得されます。

Path 値は、データ ソース関数の必須パラメーターから導出されます。 省略可能なパラメーターは、データ ソース パス識別子に考慮されません。 その結果、データ ソースの種類に関連付けられている、すべてのデータ ソース関数は、同じパラメーターを持っている必要があります。 タイプ Uri.Type が単一パラメーターを持つ関数には、特別な処理があります。 詳細については、URI パラメーター を使用して [Functions] に移動します。

Power BI Desktop の [データ ソース設定] ダイアログで、資格情報がどのように保存されるかの例を確認できます。 このダイアログでは、Kind はアイコンで表され、Path 値はテキストとして表示されます。

Note

開発中にデータ ソース関数の必須パラメーターを変更すると、以前に保存された資格情報は機能しなくなります (パス値が一致しなくなるため)。 データ ソース関数のパラメーターを変更する場合は必ず、保存されている資格情報を削除する必要があります。 互換性のない資格情報が見つかった場合、実行時にエラーが発生する可能性があります。

データ ソース パスの形式

データ ソースの Path 値は、データ ソース関数の必須パラメーターから導出されます。 必須パラメーターは、関数のメタデータに DataSource.Path = false を追加することでパスから除外できます。 詳細については、「データ ソース パスから必要なパラメーターを除外する」を参照してください。

既定では、実際の文字列値は、Power BI Desktop の [データ ソース設定] ダイアログと資格情報プロンプトで確認できます。 Data Source Kind 定義に Label 値が含まれている場合は、代わりにラベルの値が表示されます。

たとえば、HelloWorldWithDocs サンプルのデータ ソース関数には、次の署名があります。

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

この関数には、text 型の必須パラメーター (message) が 1 つあり、データ ソース パスの計算に使用されます。 省略可能なパラメーター count は無視できます。 パスは次のように表示されます。

資格情報プロンプト

データ ソース設定 UI

ラベル値が定義されている場合、データ ソース パス値は表示されません。

Note

現在、関数に必須パラメーターがある場合は、ユーザーが入力したさまざまな資格情報を区別できないため、データ ソースのラベルを含めないことをお勧めします。 今後はこの点を改善して、データ コネクタが独自のカスタム データ ソース パスを表示できるようにしたいと考えています。

データ ソース パスから必須パラメーターを除外する

関数パラメーターを必須にしたいが、データ ソース パスの一部には含めたくないという場合は、関数ドキュメントのメタデータに DataSource.Path = false を追加できます。 このプロパティは、関数の 1 つ以上のパラメーターに追加できます。 このフィールドは、データ ソース パスから値を削除する (つまり、TestConnection 関数に渡されなくなる) ため、データ ソースの識別やユーザー資格情報の区別に必要のないパラメーターにのみ使用する必要があります。

たとえば、HelloWorldWithDocs サンプルのコネクタでは、異なる message 値に対して異なる資格情報が必要になります。 message パラメーターに DataSource.Path = false を追加すると、その値がデータ ソース パスの計算から除外され、コネクタは実質的に "シングルトン" になります。 すべての 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);