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

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

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

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

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

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

[前提条件]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

さらに、サービスプリンシパルが基盤となるデータソース(レイクハウス、ウェアハウス、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 で複数のデータ ソースに対してクエリを実行する方法について説明します。