GraphQL 用の Fabric API でサービス プリンシパルを使用する

サービス プリンシパルを使用すると、GraphQL 用の Fabric API に対する非対話型のプログラムによる認証が有効になります。 ユーザーが対話形式でサインインする必要があるユーザー プリンシパルとは異なり、サービス プリンシパルはアプリケーション資格情報 (クライアント ID とシークレット) を使用して自動的に認証します。 これにより、バックエンド サービス、自動化されたワークフロー、CI/CD パイプライン、およびユーザー操作なしで実行されるアプリケーションに最適です。

このガイドでは、Microsoft Entra アプリ登録を作成し、サービス プリンシパルとして構成し、Fabric GraphQL API へのアクセス権を付与する方法について説明します。 認証に必要な資格情報を取得し、サンプル コードを使用してセットアップをテストする方法について説明します。

サービス プリンシパルを利用するのは誰か

サービス プリンシパル認証は、次の目的で設計されています。

• Fabric のレイクハウスとウェアハウスにアクセスする自動化された ETL プロセスとスケジュールされたデータ操作を構築するデータ エンジニア
• Fabric データをプログラムで使用するサーバー間アプリケーションを作成するバックエンド開発者
• ファブリック ワークスペース管理者 がデータ アクセス用の無人サービスとバックグラウンド プロセスを設定する
• Fabric データ ソースと対話する CI/CD パイプラインを実装する DevOps エンジニア
• 非対話型の Fabric データ アクセスを必要とする自動化されたワークフローを作成する統合開発者

[前提条件]

サービス プリンシパル認証を設定する前に、次のことを確認してください。

• 管理者アクセス許可を持つ Microsoft Fabric ワークスペース
• ワークスペース内の GraphQL 用の既存の API。 Fabric での GraphQL 用 API の作成とデータの追加に関する説明を参照してください。
• Microsoft Entra ID でアプリ登録を作成するためのアクセス許可
• Fabric でサービス プリンシパル設定を有効にするテナント管理者アクセス (または、これを有効にするように管理者に依頼する)

手順 1: Microsoft Entra アプリの登録を作成する

「Microsoft Entra アプリの登録」の完全なガイドに従って、サービス プリンシパルを作成してアプリの登録を作成します。

サービス プリンシパルのキー ポイント:

• リダイレクト URI と認証プラットフォームをスキップする (対話型アプリにのみ必要)
• スキップ API のアクセス許可とスコープ (サービス プリンシパルは委任されたアクセス許可を使用しません)
• 適切な有効期限が設定された証明書とシークレットの下にクライアント シークレットを作成する

手順 2: Fabric テナント設定でサービス プリンシパルを有効にする

ファブリック テナント管理者は、サービス プリンシパルの使用を有効にする必要があります。

1. Fabric ポータルで、管理ポータルに移動します>テナント設定
2. [開発者設定] で、サービス プリンシパルで Fabric API を使用できるようにする
3. を選択し、 を適用する

この設定により、アクセス許可の割り当てのためにアプリの登録が Fabric に表示されます。 詳細については、「 ID のサポート」を参照してください。

手順 3: Fabric でアクセス許可を付与する

サービス プリンシパルには、次の 2 つのレベルのアクセスが必要です。

オプション A: 個々の API アクセス許可 (運用環境に推奨)

1. Fabric ポータルで、GraphQL API を含むワークスペースを開きます
2. API 項目の横にある省略記号 (...) を選択します
3. [ アクセス許可の管理] を選択する
4. [ ユーザーの追加] を選択する
5. アプリ登録名を検索して選択する
6. [ クエリと変更の実行] を選択する (実行アクセス許可を付与)
7. [許可] を選択します。

さらに、サービス プリンシパルに基になるデータ ソース (Lakehouse、Data Warehouse、または SQL データベース) に対する適切な読み取り/書き込みアクセス許可があることを確認します。

オプション B: ワークスペースロール (開発/テスト用に簡単)

共同作成者ロールを持つワークスペース メンバーとしてアプリの登録を追加します。 これにより、GraphQL API とワークスペース内のすべてのデータ ソースの両方へのアクセスが許可されます。

1. Fabric ポータルでワークスペースを開く
2. [ アクセスの管理] を選択する
3. [ユーザーまたはグループの追加] を選択する
4. アプリの登録名を検索する
5. 共同作成者ロールを選択する
6. 追加を選択する

サービス プリンシパル認証をテストする

構成したら、アクセス トークンを取得して GraphQL API を呼び出して、サービス プリンシパルをテストします。

Node.js を使用してアクセス トークンを取得する

@azure/identity パッケージのインストール:

npm install @azure/identity

アクセス トークンを取得するファイルを作成します。

const { ClientSecretCredential } = require('@azure/identity');

// Define your Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

const scope = "https://api.fabric.microsoft.com/.default"; // The scope of the token to access Fabric

// Create a credential object with service principal details
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Function to retrieve the token
async function getToken() {
    try {
        // Get the token for the specified scope
        const tokenResponse = await credential.getToken(scope);
        console.log("Access Token:", tokenResponse.token);
    } catch (err) {
        console.error("Error retrieving token:", err.message);
    }
}

ファイルを保存して実行します。

node getToken.js

これにより、Microsoft Entra ID からアクセス トークンが取得されます。

PowerShell を使用して GraphQL API を呼び出す

トークンを使用して GraphQL API に対してクエリを実行します。

$headers = @{
    Authorization = "Bearer <YOUR_TOKEN>"
    'Content-Type' = 'application/json'
}

$body = @{
    query = @"
    <YOUR_GRAPHQL_QUERY>
"@
}

# Make the POST request to the GraphQL API
$response = Invoke-RestMethod -Uri "<YOUR_GRAPHQL_API_ENDPOINT>" -Method POST -Headers $headers -Body ($body | ConvertTo-Json)

# Output the response
$response | ConvertTo-Json -Depth 10 

cURL を使用して GraphQL API を呼び出す

cURL を使用して API にクエリを実行する:

curl -X POST <YOUR_GRAPHQL_API_ENDPOINT> \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"query": "<YOUR_GRAPHQL_QUERY(in a single line)>"}'

完全な Node.js 例 (トークン + API 呼び出し)

依存関係をインストールします。

npm install @azure/identity axios

トークンを取得して API を呼び出す完全な例を作成します。

const { ClientSecretCredential } = require('@azure/identity');
const axios = require('axios');

// Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

// GraphQL API details
const graphqlApiUrl = "YOUR_GRAPHQL_API_ENDPOINT>";
const scope = "https://api.fabric.microsoft.com/.default"; // The scope to request the token for

// The GraphQL query
const graphqlQuery = {
  query: `
  <YOUR_GRAPHQL_QUERY>
  `
};

// Function to retrieve a token and call the GraphQL API
async function fetchGraphQLData() {
  try {
    // Step 1: Retrieve token using the ClientSecretCredential
    const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    const tokenResponse = await credential.getToken(scope);
    const accessToken = tokenResponse.token;

    console.log("Access token retrieved!");

    // Step 2: Use the token to make a POST request to the GraphQL API
    const response = await axios.post(
      graphqlApiUrl,
      graphqlQuery,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Step 3: Output the GraphQL response data
    console.log("GraphQL API response:", JSON.stringify(response.data));
    
  } catch (err) {
    console.error("Error:", err.message);
  }
}

// Execute the function
fetchGraphQLData();

保存して実行します。

node callGraphQL.js

トラブルシューティング

Fabric でアプリの登録が表示されない

• テナント設定で サービス プリンシパルが Fabric API を使用できることを 確認する
• 変更が反映されるまで設定を有効にしてから数分待ちます

認証エラー

• テナント ID、クライアント ID、クライアント シークレットが正しいことを確認する
• クライアント シークレットの有効期限が切れていないことを確認する
• スコープを使用していることを確認する https://api.fabric.microsoft.com/.default

アクセス許可エラー

• サービス プリンシパルに GraphQL API に対する実行アクセス許可があることを確認します
• サービス プリンシパルが基になるデータ ソースへの読み取り/書き込みアクセス権を持っているかどうかを確認する
• ワークスペース レベルのアクセス許可を使用している場合、ワークスペース ロールが共同作成者以上であることを確認する

関連コンテンツ

• Azure で Microsoft Entra アプリを作成する
• Fabric で GraphQL 用 API を作成し、データを追加する方法について説明します。
• Fabric API for GraphQL で複数のデータ ソースに対してクエリを実行する方法について説明します。