搭配 GraphQL 的網狀架構 API 使用服務主體

2025-06-10

雖然要按照連結應用程式一節中的步驟才能取得用戶主體的存取權，但也可以透過服務主體來存取 GraphQL API。

請遵循連線應用程式的步驟來建立 Microsoft Entra 應用程式，但請注意，對於服務主體不需要範疇。在新應用程式中，在 [憑證和秘密] 底下新增客戶端密碼，如需詳細資訊，請參閱註冊 Microsoft Entra 應用程式並建立服務主體。
請確定租用戶系統管理員已啟用 Fabric 中的服務主體使用方式。在租使用者管理入口網站中，移至 [ 租用戶設定]。在 [開發人員設定] 底下，啟用服務主體可以使用網狀架構 API。 啟用此設定後，應用程式會顯示在 Fabric 入口網站中，以供角色或權限分配。您可以找到身分識別支持的詳細資訊。
服務主體需要存取 GraphQL API 和數據源，更具體地說，對 GraphQL API 執行許可權，以及據以選擇之數據源所需的讀取或寫入許可權。在網狀架構入口網站中，開啟工作區，然後選取 API 旁邊的省略號。選取 [ 管理 API 的許可權 ]，然後 選取 [新增使用者]。新增應用程式，然後選取 [ 執行查詢和突變]，以提供服務主體所需的執行許可權。為了進行測試，實作 API 和數據源所需許可權的最簡單方式，就是將應用程式新增為具有 GraphQL API 和數據源專案所在參與者角色的工作區成員。

由於服務主體需要憑證或客戶端密碼，因此在單頁應用程式中的 Microsoft 驗證連結庫（MSAL）不支援它，例如我們在最後一個步驟中建置的 React 應用程式。您可以根據您的需求和使用案例，利用妥善定義的授權邏輯適當保護後端服務。

一旦您的 API 設定為由服務主體存取，您就可以在本機使用簡單的Node.JS應用程式在本機測試它：

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.JS套件管理員安裝相依性（@azure/identity）之後，使用所需的資訊修改檔案，儲存並執行它（node <filename.js>），您將可以從 entra Microsoft 擷取權杖。

然後，您可以使用 PowerShell 來叫用 GraphQL API，方法是將適當的詳細數據取代為您 剛才擷取的令牌 、 您想要執行的 GraphQL 查詢 ，以及 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 來達成相同的結果：

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程式代碼可以稍微修改，並搭配額外的相依性（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();

共用方式為

搭配 GraphQL 的網狀架構 API 使用服務主體

相關內容

意見反應

其他資源