DAX クエリの実行 REST API のベスト プラクティス

運用環境のワークロードで DAX クエリの実行 REST API を最大限に活用するには、次の推奨事項に従います。

適切なエンドポイントを選択する

注

DAX クエリの実行 API は、Power BI容量 (Premium、Fabric、または Embedded) に存在するセマンティック モデルでのみ使用できます。 容量の割り当てのないセマンティック モデルはサポートされていません。

Power BIには、DAX クエリを実行するための 2 つの REST API が用意されています。 クライアントの機能に一致するものを選択します。

  • DAX クエリの実行 (矢印) - クライアント アプリケーションがバイナリの Arrow IPC ストリームを使用できる場合に使用します。 Arrow は、より小さなペイロード、無損失型の忠実性、およびゼロ コピーの逆シリアル化を pandas、Polars、Apache Spark などの列指向フレームワークに提供します。 この API では、 queryTimeout や resultsetRowcountLimitなどの高度なパラメーターもサポートされています。 Premium またはFabric容量が必要です。
  • Execute Queries (JSON) — コンシューマーが低コード/コードなしのプラットフォーム、Power Automate フロー、または JSON のみを解析できる任意のツールである場合に使用します。 この API は Pro、PPU、Premium/Fabric 容量で動作しますが、クエリあたり 100,000 行と 1,000,000 個の値というハード制限があります。

一般に、結果セットが数百行を超える場合、分析パイプラインにフィードする場合、または正確な型の忠実性が必要な場合は、Arrow で DAX クエリの実行 API を使用します。

Arrow エンドポイントの DAX クエリを最適化する

効率的な DAX により、クエリの実行時間と応答ペイロードのサイズの両方が削減されます。

  • 必要な列のみを返します。 テーブル全体を返す代わりに、 SELECTCOLUMNS または明示的な列リストを使用します。 余分な列はすべて、スキーマとレコードのバッチ サイズに追加されます。
  • SUMMARIZECOLUMNSでADDCOLUMNSよりもFILTERを優先します。 SUMMARIZECOLUMNS は、VertiPaq エンジンでより効率的なクエリ プランを生成します。
  • TOPNを使用して行を制限します。 上位の結果のみが必要な場合、 TOPN はすべての行を転送してクライアント側でフィルター処理するのではなく、制限をエンジンにプッシュします。
  • クエリで複雑な計算列を使用しないようにします。 メジャーと集計は問題ありませんが、大きなテーブルの行レベルの計算では実行速度が大幅に低下する可能性があります。
  • 1 つの要求で複数の EVALUATE ステートメントを結合します。 DAX クエリの実行 API では、1 つのEVALUATE文字列内で複数のquery ステートメントがサポートされ、それぞれが個別の結果セットを返します。 これにより、個別の HTTP ラウンド トリップのオーバーヘッドが回避されます。

認証を効率的に管理する

  • トークンをキャッシュして再利用します。 MSAL の組み込みトークン キャッシュを使用して、すべての要求でMicrosoft Entra IDを呼び出さないようにします。 機密クライアント フローの場合、同じ ConfidentialClientApplication インスタンスを再利用すると、MSAL によってトークンが自動的にキャッシュされます。
  • サービスには機密クライアント資格情報を使用します。 無人中間層サービスの場合は、委任されたユーザー トークンではなく、クライアント資格情報 (クライアント シークレットまたは証明書) を使用します。 これにより、サインインしているユーザー セッションへの依存関係が回避されます。
  • Azureでマネージド ID を優先します。 サービスが Azure (App Service、Functions、AKS) で実行されている場合は、マネージド ID を使用して資格情報の管理を完全に排除します。
  • トークンの有効期限を適切に処理します。 通常、アクセス トークンは 1 時間後に期限切れになります。 401 Unauthorized応答を確認し、再試行する前にトークンを更新します。

エラーと再試行を処理する

DAX クエリの実行 API は、次の 2 つの方法でエラーを返すことができます。

  1. HTTP レベルのエラー — JSON エラー本文を含む標準の HTTP 状態コード。 一般的なコード:

    ステータスコード Meaning アクション
    400 正しくない要求 (無効な DAX、パラメーターがありません) 要求を修正します。再試行しないでください。
    401 未承認 (期限切れまたは無効なトークン) トークンを更新し、1 回再試行します。
    403 禁止 (アクセス許可が不十分) 呼び出し元に、セマンティック モデルに対するビルドと読み取りのアクセス許可があることを確認します。
    429 要求が多すぎます（制限されています） Retry-After ヘッダーの期間を待ってから、再試行します。
    500 / 502 / 503 一時的なサーバー エラー 指数バックオフを使用して再試行します。

  2. ストリーム レベルのエラー — HTTP 200 で、エラー行セットが矢印応答に埋め込まれています。 IsError=trueのArrowスキーマメタデータを確認し、FaultCodeとFaultStringのメタデータ値およびエラー行を読み取り、詳細な位置情報を取得します。

一時的なエラーの場合は、ジッターを伴う指数バックオフを実装します。 1 秒から開始し、再試行ごとに 2 回、上限を 30 秒にします。 再試行回数を 3 回または 4 回に制限します。

結果セットのサイズを制御する

大きな結果セットは、サービス内の容量と呼び出し元のクライアントの両方でメモリを消費します。 各要求は、容量のメモリ制限によってバインドされます。

結果セットを管理しやすくするには:

  • 要求本文で resultsetRowcountLimit を設定します。 これにより、結果セットごとにサーバー側の行制限が適用されます。 コンシューマーに必要な行が 10,000 行のみであることがわかっている場合は、制限を明示的に設定します。
  • DAX クエリで TOPN を使用します。 TOPN はエンジン レベルで行を制限します。これは、クライアント側の切り捨てよりも効率的です。
  • レコード バッチを段階的に処理します。 矢印の応答は、最大 100,000 行のレコード バッチに分割されます。 Pythonでは、大きな結果を処理するときに reader.read_next_batch() を呼び出す代わりに、reader.read_all() を使用してバッチを反復処理し、メモリ使用量を一定に保ちます。

中間層サービスをセキュリティで保護する

ダウンストリーム コンシューマーに対して DAX クエリをプロキシする中間層サービスを構築する場合:

  • 呼び出し元 ID を検証します。 クエリをPower BIに転送する前に、Microsoft Entra IDまたは別の ID プロバイダーで受信要求を認証します。 DAX クエリの実行エンドポイントをオープン プロキシとして公開しないでください。
  • 最小限の特権を適用します。 サービス プリンシパルに必要なアクセス許可のみを付与します (特定のセマンティック モデルでのビルドと読み取り)。 API アクセスには、ワークスペース管理者ロールまたはテナント管理者ロールを使用しないでください。
  • コードに資格情報を埋め込まない。 クライアント シークレットをAzure Key Vaultに格納するか、マネージド ID を使用します。 シークレットを定期的にローテーションします。
  • DAX 入力をサニタイズします。 中間層が呼び出し元からの DAX クエリ テキストを受け入れる場合は、予期しない操作が挿入されないように入力を検証します。
  • effectiveUsername パラメーターは注意して使用してください。 このパラメーターは、特定のユーザーのためにRow-Level Securityを適用します。 指定したユーザーを偽装する権限が呼び出し元 ID に付与されていることを確認します。

監視とログ記録

API の使用状況の正常性とパフォーマンスを追跡します。

  • ログ クエリ メタデータ - 各要求のクエリ テキスト、応答サイズ、HTTP 状態、期間を記録します。 これは、低速なクエリと予期しないエラーの急増を特定するのに役立ちます。
  • 調整率を監視する - 429 応答を要求総数に対する割合として追跡します。 上昇傾向は、要求の頻度を減らすか、時間の間に負荷を分散させる必要があることを示しています。
  • 逆シリアル化時間を測定 する — 矢印応答の場合は、HTTP ラウンドトリップ時間とは別に、レコード バッチの読み取りと具体化に費やされた時間をログに記録します。 これは、ネットワーク待機時間とクライアント側の処理を区別するのに役立ちます。
  • Application Insights またはそれと同等 — 中間層がAzureで実行されている場合は、Application Insights で依存関係の追跡、障害アラート、およびエンドツーエンドの分散トレースを取得できるようにします。
  • トークン キャッシュヒット率を追跡する — キャッシュヒット率が低いということは、頻繁なトークン取得呼び出しを意味します。これは待機時間を追加し、MSAL キャッシュが正しく構成されていないことの兆候です。

関連するコンテンツ

  • Last updated on