บทช่วยสอน: สร้างบริการระดับกลาง .NET ด้วย Execute DAX Queries REST API

ในบทช่วยสอนนี้ คุณใช้ Microsoft ตัวอย่าง Samples.XMLA.ExecuteQueries — เว็บ API .NET ที่พร็อกซีคิวรี DAX ผ่านตําแหน่งข้อมูล XMLA โดยใช้ ADOMD.NET — และปรับเปลี่ยนเพื่อใช้ ดําเนินการคิวรี DAX REST API ซึ่งส่งกลับผลลัพธ์ในรูปแบบ IPC ลูกศร Apache ตัวอย่างมีกรอบงานระดับกลาง (การกําหนดเส้นทาง การจํากัดอัตรา โพรบความสมบูรณ์) บทช่วยสอนนี้แสดงวิธีแทนที่ระบบประปาการดําเนินการคิวรี XMLA/ADOMD ด้วยการเรียก REST API และการจัดการการตอบสนอง Arrow IPC

ข้อกำหนดเบื้องต้น

  • .NET 8 SDK หรือใหม่กว่า
  • พื้นที่ทํางาน Power BI บนความจุ Premium หรือ Fabric ที่มีแบบจําลองความหมายอย่างน้อยหนึ่งแบบ
  • การลงทะเบียนแอป Microsoft Entra ที่มีข้อมูลลับของไคลเอ็นต์
  • บริการหลักถูกเพิ่มเป็นสมาชิกพื้นที่ทํางานที่มีบทบาท ผู้สนับสนุน (หรือสูงกว่า)
  • เปิดใช้งานการตั้งค่าผู้เช่าต่อไปนี้:
    • ชุดข้อมูลดําเนินการคิวรี REST API และ อนุญาตให้บริการหลักใช้ Power BI APIs (ภายใต้ การตั้งค่านักพัฒนา)
    • อนุญาตตําแหน่งข้อมูล XMLA และวิเคราะห์ใน Excel ด้วยโมเดลความหมายภายในองค์กร (ภายใต้ การตั้งค่าการรวม)

สําหรับรายละเอียดเกี่ยวกับสถาปัตยกรรมบริการตัวอย่าง โปรดดู sample README

ก่อนที่คุณจะเริ่มต้น

บริการตัวอย่างใช้จุดสิ้นสุด XMLA กับ ADOMD.NET บทช่วยสอนนี้จะแปลงให้ใช้ Execute DAX Queries REST API ซึ่งส่งกลับผลลัพธ์ในรูปแบบ Apache Arrow IPC ทั้งสองวิธีช่วยให้คุณสามารถเรียกใช้คิวรี DAX กับแบบจําลองความหมายของ Power BI ได้ แต่แตกต่างกันในลักษณะที่สําคัญ

XMLA / อะดอมด์ .NET เรียกใช้คิวรี DAX REST API
พิธีสาร XMLA ผ่าน HTTPS (ไบนารีที่เป็นกรรมสิทธิ์) REST STANDARD (HTTP POST / การตอบสนอง)
ไลบรารีไคลเอ็นต์ Microsoft.AnalysisServices.AdomdClient — เน้น Windows (มีแพ็คเกจ .NET Core แต่รองรับข้ามแพลตฟอร์มที่จํากัด) จัดการเซสชันและการเชื่อมต่อ HttpClient + Apache.Arrow - น้ําหนักเบาข้ามแพลตฟอร์มไร้สัญชาติ
การรับรองความถูกต้อง สตริงการเชื่อมต่อพร้อมโทเค็นการเข้าถึง เซสชันระดับการเชื่อมต่อ โทเค็นผู้ถือต่อคําขอ ไม่มีสถานะเซสชัน
รูปแบบการตอบกลับ ชุดแถวแบบตารางที่แยกวิเคราะห์โดยไลบรารีไคลเอ็นต์ ADOMD Apache Arrow IPC — รูปแบบไบนารีแบบคอลัมน์ที่รองรับระบบนิเวศในวงกว้าง (Python, R, Spark, DuckDB)
การจัดการการเชื่อมต่อ ต้องมีการรวมเพื่อตัดจําหน่ายค่าใช้จ่ายในการตั้งค่าเซสชัน HTTP แบบไร้สัญชาติ — ไม่จําเป็นต้องรวมกลุ่ม MSAL จัดการการแคชโทเค็น
เหมาะสําหรับ การผสานรวมแบบดั้งเดิม, การสืบค้น MDX, การควบคุมเซสชันแบบละเอียด บริการใหม่ที่คุณต้องการการผสานรวม HTTP ที่ง่ายขึ้น ประสิทธิภาพแบบคอลัมน์ หรือผู้บริโภคข้ามภาษา

เลือก ดําเนินการคิวรี DAX REST API เมื่อคุณกําลังสร้างบริการใหม่ หรือผู้บริโภคดาวน์สตรีมของคุณจะได้รับประโยชน์จาก Arrow IPC (ตัวอย่างเช่น ไปป์ไลน์การวิเคราะห์ สมุดบันทึก Python หรือฐานข้อมูลแบบคอลัมน์) เก็บ XMLA/ADOMD ไว้หากคุณต้องการการสนับสนุน MDX หรือพึ่งพาคุณลักษณะระดับเซสชัน เช่น สมาชิกที่คํานวณได้ที่กําหนดขอบเขตไว้ที่เซสชัน

1 - โคลนและตรวจสอบตัวอย่าง

โคลนที่เก็บและยืนยันว่าคอมไพล์:

git clone https://github.com/dbrownems/Microsoft.Samples.XMLA.ExecuteQueries.git
cd Microsoft.Samples.XMLA.ExecuteQueries
dotnet build

โซลูชันประกอบด้วยสองโครงการ: บริการระดับกลาง (Microsoft.Samples.XMLA.ExecuteQueries) และไคลเอ็นต์ทดสอบโหลด (Tester) คุณไม่จําเป็นต้องเรียกใช้บริการดั้งเดิมกับพื้นที่ทํางานแบบสด เพียงตรวจสอบว่าบิลด์สําเร็จก่อนที่จะทําการเปลี่ยนแปลง

2 - อัปเดตการพึ่งพา NuGet

ในโปรเจ็กต์ Microsoft.Samples.XMLA.ExecuteQueries ให้ลบแพ็กเกจ ADOMD.NET และเพิ่มแพ็กเกจสําหรับ Arrow API:

cd Microsoft.Samples.XMLA.ExecuteQueries
dotnet remove package Microsoft.AnalysisServices.AdomdClient.NetCore.retail.amd64
dotnet add package Apache.Arrow
dotnet add package Microsoft.Identity.Client

เก็บแพ็คเกจ Microsoft.PowerBI.Api ไว้หากคุณต้องการนําชนิดโมเดลคําขอ/การตอบกลับกลับมาใช้ใหม่ มิฉะนั้นให้ลบออกและกําหนด DTO ของคุณเอง

3 - แทนที่การรวมการเชื่อมต่อ ADOMD ด้วยการแคชโทเค็น MSAL

ตัวอย่างใช้เพื่อ AdomdConnectionPool.cs รวมการเชื่อมต่อ XMLA Arrow API เป็นตําแหน่งข้อมูล REST แบบไร้สถานะ ดังนั้นคุณจึงแทนที่การรวมการเชื่อมต่อด้วยการแคชโทเค็น MSAL

สร้างไฟล์ TokenService.csใหม่ :

using Microsoft.Identity.Client;

public class TokenService
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes =
        { "https://analysis.windows.net/powerbi/api/.default" };

    public TokenService(IConfiguration config)
    {
        _app = ConfidentialClientApplicationBuilder
            .Create(config["PowerBI:ClientId"])
            .WithClientSecret(config["PowerBI:ClientSecret"])
            .WithAuthority(AzureCloudInstance.AzurePublic,
                config["PowerBI:TenantId"])
            .Build();
    }

    public async Task<string> GetAccessTokenAsync()
    {
        var result = await _app
            .AcquireTokenForClient(_scopes).ExecuteAsync();
        return result.AccessToken;
    }
}

MSAL แคชโทเค็นโดยอัตโนมัติ — การเรียกครั้งต่อๆ ไปจะส่งคืนโทเค็นที่แคชไว้จนกว่าจะหมดอายุ

ลบ AdomdConnectionPool.cs และ AdomdExtensions.cs. พวกเขาไม่จําเป็นอีกต่อไป

4 - อัปเดตตัวจัดการคิวรีเพื่อเรียก Arrow API

ใน Handlers.csแทนที่การดําเนินการคิวรี ADOMD ด้วยการเรียก HTTP ไปยังจุดสิ้นสุดดําเนินการคิวรี DAX

ลบการอ้างอิง ADOMD ทั้งหมด (AdomdConnectionPool, , , AdomdCommand) WrappedConnectionAdomdConnection เปลี่ยนการขึ้นต่อกันที่แทรกของตัวจัดการเป็น TokenService และ HttpClient แทนที่จะเป็นพูลการเชื่อมต่อและการค้นหาพื้นที่ทํางาน

สร้าง REST API URL จากพื้นที่ทํางานและชุดข้อมูล GUID ที่มีอยู่แล้วในพารามิเตอร์เส้นทาง:

var url = $"https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}"
        + $"/datasets/{datasetId}/executeDaxQueries";

ลงรายการบัญชีคิวรี DAX ด้วยเนื้อหาคําขอ JSON:

var token = await tokenService.GetAccessTokenAsync();

using var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent(
    JsonSerializer.Serialize(new { query, queryTimeout = 120 }),
    Encoding.UTF8, "application/json");

var response = await httpClient.SendAsync(
    request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();

ใช้ HttpCompletionOption.ResponseHeadersRead เพื่อให้เนื้อหาการตอบสนองสตรีมโดยไม่มีการบัฟเฟอร์ ซึ่งมีความสําคัญสําหรับชุดผลลัพธ์ขนาดใหญ่

5 - จัดการการตอบสนอง Arrow IPC

API ดําเนินการคิวรี DAX ส่งคืนสตรีม IPC ลูกศรอย่างน้อยหนึ่งสตรีมที่เชื่อมต่อกันในเนื้อหาการตอบสนอง แต่ละสตรีมจะมีข้อมูลเมตาของสคีมาที่ระบุวัตถุประสงค์:

  • ผลลัพธ์ข้อมูล — ผลลัพธ์การสืบค้น (ไม่มีค่าสถานะข้อมูลเมตาพิเศษ)
  • ผลลัพธ์ข้อผิดพลาด — IsError=true ในเมตาดาต้า Schema ที่มีFaultCodeค่า และFaultString
  • เมตริกการดําเนินการ — IsExecMetrics=true (หากคุณร้องขอเมตริกผ่าน executionMetrics พารามิเตอร์)

แทนที่ DataResult.cs ด้วยตรรกะที่จัดการการตอบสนองของลูกศร หากระดับกลางของคุณเพียงแค่ส่งต่อ Arrow IPC ไปยังผู้บริโภคดาวน์สตรีม ให้สตรีมไบต์ผ่านโดยไม่ต้อง deserialization:

context.Response.ContentType = "application/vnd.apache.arrow.stream";
await response.Content.CopyToAsync(context.Response.Body);

หากคุณต้องการตรวจสอบผลลัพธ์หรือแปลงรูปแบบ ให้ deserialize สตรีมลูกศรด้วย ArrowStreamReader:

using var stream = await response.Content.ReadAsStreamAsync();
using var reader = new ArrowStreamReader(stream);

while (true)
{
    var batch = await reader.ReadNextRecordBatchAsync();
    if (batch == null) break;
    // Process batch — convert to JSON, filter rows, etc.
}

ตรวจสอบข้อมูลเมตาของสคีมาเพื่อตรวจหาการตอบสนองข้อผิดพลาด:

var metadata = reader.Schema.Metadata;
if (metadata.TryGetValue("IsError", out var isError)
    && isError == "true")
{
    var faultCode = metadata.GetValueOrDefault(
        "FaultCode", "Unknown");
    var faultString = metadata.GetValueOrDefault(
        "FaultString", "Unknown error");
    // Return error to caller
}

6 - ลดความซับซ้อนของการกําหนดค่าพื้นที่ทํางาน

ตัวอย่าง appsettings.json กําหนดค่าจุดสิ้นสุด XMLA และการค้นหาชื่อชุดข้อมูลเนื่องจาก ADOMD เชื่อมต่อด้วยชื่อแค็ตตาล็อก Arrow REST API ใช้พื้นที่ทํางานและชุดข้อมูล GUID โดยตรงจาก URL คําขอ ดังนั้นการกําหนดค่าจึงง่ายขึ้น

อัปเดต appsettings.json ด้วยข้อมูลประจําตัวของบริการหลักและลบฟิลด์เฉพาะ XMLA:

{
  "PowerBI": {
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_APP_CLIENT_ID",
    "ClientSecret": "YOUR_CLIENT_SECRET"
  }
}

Workspacesส่วนที่มี XmlaEndpoint และ Datasets อาร์เรย์ ไม่จําเป็นอีกต่อไป คุณสามารถลบ Workspace.cs และ Dataset.csหรือนํารายการมาใช้ Datasets ใหม่เป็นรายการที่อนุญาตสําหรับการกํากับดูแล (จํากัดชุดข้อมูลที่บริการสามารถสืบค้นได้)

7 - ลงทะเบียนบริการและอัปเดตการกําหนดเส้นทาง

ใน Program.csแทนที่พูล ADOMD และการลงทะเบียนพื้นที่ทํางานด้วยบริการใหม่:

builder.Services.AddSingleton<TokenService>();
builder.Services.AddHttpClient();

อัปเดตเส้นทางให้ตรงกับรูปแบบปลายทาง Execute DAX Queries:

app.MapPost(
    "/v1.0/myorg/groups/{workspaceId:Guid}"
    + "/datasets/{datasetId:Guid}/executeDaxQueries",
    Handlers.ExecuteDaxQueriesInGroup);

ตัวจํากัดอัตรา โพรบความสมบูรณ์ และตัวนับคําขอที่มีอยู่จากตัวอย่างยังคงมีประโยชน์ as-is

8 - ทดสอบบริการ

เรียกใช้บริการ:

dotnet run --project Microsoft.Samples.XMLA.ExecuteQueries

จากเทอร์มินัลอื่น ให้ส่งคิวรี DAX:

curl -X POST https://localhost:3000/v1.0/myorg/groups/YOUR_WORKSPACE_ID/datasets/YOUR_DATASET_ID/executeDaxQueries \
  -H "Content-Type: application/json" \
  -d '{"query": "EVALUATE TOPN(5, '\''DimProduct'\'')"}'

การตอบสนองคือสตรีม IPC ลูกศรไบนารี บันทึกลงในไฟล์และตรวจสอบด้วย Python:

curl -s -o result.arrow https://localhost:3000/v1.0/myorg/groups/YOUR_WORKSPACE_ID/datasets/YOUR_DATASET_ID/executeDaxQueries \
  -H "Content-Type: application/json" \
  -d '{"query": "EVALUATE TOPN(5, '\''DimProduct'\'')"}'

python -c "
import pyarrow as pa
reader = pa.ipc.open_stream('result.arrow')
table = reader.read_all()
print(table.schema)
print(table.to_pandas())
"

สรุปข้อมูลการเปลี่ยนแปลง

ไฟล์ต้นฉบับ แอคชัน
AdomdConnectionPool.cs ลบ — แทนที่ด้วยการแคชโทเค็น MSAL ใน TokenService.cs
AdomdExtensions.cs ลบ — ไม่จําเป็นต้องใช้ตรรกะการสตรีม JSON อีกต่อไป
DataResult.cs เขียนใหม่ — สตรีม Arrow IPC ผ่าน หรือ deserialize ด้วย ArrowStreamReader
Handlers.cs เขียนใหม่ — HTTP POST เพื่อเรียกใช้ API แบบสอบถาม DAX แทนการดําเนินการ ADOMD
Workspace.cs / Dataset.cs ลดความซับซ้อนหรือลบ — REST API ใช้ GUID ไม่ใช่ชื่อแค็ตตาล็อก
Program.cs อัปเดต — ลงทะเบียน TokenService และ IHttpClientFactory; อัปเดตเส้นทาง
appsettings.json ลดความซับซ้อน — ข้อมูลประจําตัวหลักของบริการเท่านั้น ลบการกําหนดค่า XMLA
.csproj Update — ลบแพ็คเกจ ADOMD; เพิ่ม Apache.Arrow และ Microsoft.Identity.Client

ล้างแหล่งข้อมูล

เมื่อคุณทําการทดสอบเสร็จแล้ว ให้ทําดังนี้

  1. หยุดบริการภายในเครื่อง (กด Ctrl+C ในเทอร์มินัล)
  2. หากคุณสร้างการลงทะเบียนแอป Microsoft Entra สําหรับบทช่วยสอนนี้เพียงอย่างเดียว ให้ไปที่พอร์ทัล Azure และลบออก
  3. ลบบริการหลักออกจากพื้นที่ทํางาน Power BI ถ้าไม่ต้องการอีกต่อไป