หมายเหตุ
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลอง ลงชื่อเข้าใช้หรือเปลี่ยนไดเรกทอรีได้
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลองเปลี่ยนไดเรกทอรีได้
ในบทช่วยสอนนี้ คุณใช้ 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 |
ล้างแหล่งข้อมูล
เมื่อคุณทําการทดสอบเสร็จแล้ว ให้ทําดังนี้
- หยุดบริการภายในเครื่อง (กด Ctrl+C ในเทอร์มินัล)
- หากคุณสร้างการลงทะเบียนแอป Microsoft Entra สําหรับบทช่วยสอนนี้เพียงอย่างเดียว ให้ไปที่พอร์ทัล Azure และลบออก
- ลบบริการหลักออกจากพื้นที่ทํางาน Power BI ถ้าไม่ต้องการอีกต่อไป
เนื้อหาที่เกี่ยวข้อง
- ทําความเข้าใจ API คิวรี DAX
- เริ่มต้นใช้งาน REST API ดําเนินการคิวรี DAX
- บทช่วยสอน: การแยก Python ปริมาณมากสําหรับวิทยาศาสตร์ข้อมูล
- แนวทางปฏิบัติที่ดีที่สุดสําหรับ REST API ของการดําเนินการคิวรี DAX
- <ค 0>Microsoft ตัวอย่าง Samples.XMLA.ExecuteQueries (GitHub)