สร้างแอปที่เชื่อมต่อกับแบบจําลองความหมาย

ใช้เทมเพลตแอปข้อมูลร่วมกับตัวเชื่อมต่อโมเดลเชิงความหมาย Fabric เพื่อสร้างแอป Fabric เชิงวิเคราะห์ เทมเพลตนี้ให้รูปแบบการแสดงผล การจัดรูปแบบ ตารางข้อมูล และรูปแบบการตรวจสอบเบราว์เซอร์ ตัวเชื่อมต่อนี้ให้สิทธิ์เข้าถึงแบบจําลองเชิงความหมายแบบมีประเภทและมอบหมายผ่านไคลเอนต์ Fabric Apps

แอปที่สร้างด้วยเทมเพลตประกอบด้วย:

  • การยืนยันตัวตนแบบ Fabric
  • คําแนะนําการสร้าง DAX (Data Analysis Expressions) ที่มีคุณภาพสูงขึ้น
  • ส่วนประกอบภาพที่พร้อมใช้งานสําหรับองค์กร ออกแบบมาเพื่อแอปพลิเคชันเชิงวิเคราะห์
  • ตารางข้อมูล ธีม การจัดรูปแบบ และรูปแบบการตรวจสอบเบราว์เซอร์

Note

ปัจจุบัน Rayfin CLI เป็นวิธีที่รองรับในการสร้างแอปโดยใช้เทมเพลตแอปข้อมูล

เหตุใดจึงต้องใช้เทมเพลตแอปข้อมูล

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

  • ความล้มเหลวและภาพที่แตกหรือว่างเปล่ามากขึ้น
  • พฤติกรรมกราฟไม่สอดคล้องกัน
  • คําสั่ง DAX ที่ไม่จําเป็นระหว่างการพัฒนาและรันไทม์

เทมเพลตนี้ให้รูปแบบที่นํากลับมาใช้ใหม่ได้ ซึ่งช่วยเพิ่มความน่าเชื่อถือ สร้างภาพที่สอดคล้องกันมากขึ้นตามแนวทางปฏิบัติที่ดีที่สุดของการรายงาน และลดภาระการค้นหา ตัวเชื่อมต่อนี้มาตรฐานการกําหนดค่าโมเดลเชิงความหมายและการเข้าถึงขณะรันไทม์

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

  • Node.js 20 ปีขึ้นไป
  • เข้าถึง Fabric
  • พื้นที่ทํางาน Fabric ที่คุณมีสิทธิ์ ผู้สนับสนุน สมาชิก หรือผู้ดูแลระบบ
  • ปริมาณงาน Fabric Apps ที่เปิดใช้งานในผู้เช่าของคุณ ดูที่ สร้างแอป Fabric แรกของคุณ
  • เปิดใช้งานการตั้งค่าผู้เช่า Semantic Model Execute Queries REST API
  • สิทธิ์ในการสร้างและอ่านบนโมเดลเชิงความหมายที่โฮสต์บนความจุ Fabric หรือ Power BI
  • รหัสพื้นที่ทํางานและรหัสไอเท็มสําหรับโมเดลเชิงความหมาย

สร้างแอป

สร้างโปรเจกต์จากเทมเพลตแอปข้อมูล:

npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>

แทนที่<app-name>และ<workspace-name>ด้วยชื่อสําหรับแอปและพื้นที่ทํางาน Fabric ของคุณ จากนั้นเปิดโฟลเดอร์โปรเจกต์ใหม่:

cd <app-name>

เพิ่มตัวเชื่อมต่อโมเดลความหมาย

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

npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json

เพิ่มโมเดลเชิงความหมายเป็นตัวเชื่อมต่อ:

npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

คําสั่ง:

  • เพิ่มตัว salesModel เชื่อมต่อให้กับ rayfin/rayfin.yml.
  • สร้างสคีมาภายใต้ rayfin/connectors/salesModel/.
  • พิมพ์คําสั่งที่ตรงกับ npm install เวอร์ชันสําหรับแพ็กเกจตัวเชื่อมต่อ

รันคําสั่งติดตั้งที่พิมพ์โดย CLI อย่างแม่นยํา

การกําหนดค่าที่สร้างขึ้นมีลักษณะคล้ายกับตัวอย่างต่อไปนี้:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

เก็บค่าที่สร้างขึ้น version ไว้

เชื่อมต่อเทมเพลตกับโมเดลเชิงความหมาย

เทมเพลตประกอบด้วยส่วนประกอบวิเคราะห์และคําแนะนําของตัวแทนที่คุณสามารถนํากลับมาใช้กับตัวเชื่อมต่อได้ กําหนดค่าชั้นการเข้าถึงข้อมูลเพื่อสร้าง ConnectorsRayfinClient และลงทะเบียนรันไทม์โมเดลเชิงความหมาย:

Important

ใช้ไคลเอนต์ตัวเชื่อมต่อสําหรับการสืบค้นแบบจําลองเชิงความหมาย ถ้าโครงสร้างรองรับมีไคลเอนต์โมเดลเชิงความหมายอีกตัวหนึ่ง ให้แทนที่การเรียกใช้งานแทนการรักษาเส้นทางการเข้าถึงข้อมูลสองเส้นทาง

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
  connectorConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      salesModel: connectorConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

ใช้ URL API และคีย์ที่เผยแพร่ได้จากโปรเจกต์ Fabric Apps ของคุณ รักษาขั้นตอนการลงชื่อเข้าใช้ Fabric ที่มีอยู่ของเทมเพลตไว้

ส่ง DAX ผ่านตัวเชื่อมต่อ:

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  console.log(result.table.columns, result.table.rows);
} else {
  console.error(result.error.category, result.error.message);
}

แทนที่ Sales ด้วยตารางในโมเดลความหมายของคุณ ตรวจสอบสถานะที่ส่งกลับก่อนส่งคอลัมน์และแถวไปยังภาพ

สําหรับคําแนะนําเพิ่มเติมเกี่ยวกับการกําหนดค่าตัวเชื่อมต่อและความปลอดภัย ดูที่ Connect Fabric Apps to Fabric data

สร้างแอปด้วยตัวแทนโค้ด

โครงนั่งร้านมีคําแนะนําและทักษะสําหรับเจ้าหน้าที่เขียนโค้ด เปิดโปรเจกต์ในเอเจนต์ที่คุณเลือก และอธิบายกลุ่มเป้าหมาย คําถาม ปฏิสัมพันธ์ และการแสดงผลสําหรับแอป

ตัวอย่างเช่น คุณสามารถ:

  • เปิดโปรเจกต์ใน Visual Studio Code แล้วเปิดบานหน้าต่าง GitHub Copilot Chat
  • เปิดเทอร์มินัลในโปรเจกต์ แล้วรัน copilot.

ภาพหน้าจอแสดงอินเทอร์เฟซ Copilot Chat ของ GitHub ใน Visual Studio Code

ใช้พรอมต์นี้เป็นจุดเริ่มต้น:

Build an analytical Fabric app that uses the existing salesModel connector.

Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
   visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
   measure, or column names.

Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
  another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
  and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.

Give me a short implementation plan, make the changes, run the existing build,
and report the results.

ใช้ความสามารถของเทมเพลต

เทมเพลตแอปข้อมูลมีรูปแบบที่นํากลับมาใช้ใหม่สําหรับงานวิเคราะห์

Fabric Apps เป็นเว็บแอปพลิเคชันมาตรฐาน ดังนั้นคุณสามารถเพิ่มฟีเจอร์นอกเหนือจากรูปแบบเหล่านี้ได้ ฟีเจอร์ที่ไม่ได้รวมอยู่ในเทมเพลตอาจต้องการวิศวกรรมและการตรวจสอบเพิ่มเติมที่ปรับแต่งได้

ภาพ

เทมเพลตนี้ประกอบด้วยการไฮไลท์ข้ามและองค์ประกอบที่ตั้งค่าไว้ล่วงหน้าสําหรับ:

  • แผนภูมิแท่ง รวมถึงการจัดวางแนวตั้ง แนวนอน การจัดกลุ่ม และแบบซ้อน
  • แผนภูมิเส้นพร้อมเครื่องหมายเสริม
  • แผนภูมิพื้นที่
  • แผนภูมิกระจาย
  • แผนภูมิพายและโดนัท
  • แผนที่ความร้อน
  • แผนภูมิฟองสบู่
  • แผนภูมิน้ําตก
  • การ์ดค่าเดียวสําหรับการเรียก KPI
  • ภาพซ้อนและภาพรวม เช่น แถบที่มีป้ายข้อมูลและแผนภูมิเส้นสองแกน

ใช้ฟิลด์และมาตรวัดที่มีอยู่ในโมเดลความหมายที่เชื่อมต่อกัน อย่าแทนที่คําสั่งเชื่อมต่อที่ล้มเหลวด้วยข้อมูลจําลอง

คุณสามารถขอให้เอเจนต์เขียนโค้ดสร้างภาพอื่น ๆ ได้ ภาพที่ไม่มีเทมเพลตอาจต้องทําซ้ําและตรวจสอบมากขึ้น

ความสามารถของกริดข้อมูล

เทมเพลตประกอบด้วยกริดข้อมูลที่มีความสามารถที่ตั้งค่าไว้ล่วงหน้าดังนี้:

  • ส่วนหัวคอลัมน์ที่ได้จากเมตาดาต้าแบบจําลองเชิงความหมาย
  • การจัดรูปแบบหมายเลขและวันที่ต่อคอลัมน์ผ่านสตริงรูปแบบ
  • การคัดแยก
  • แถวเลื่อนได้พร้อมการจัดการโอเวอร์โฟลว์
  • รองรับธีมสว่างและมืด
  • ตัวเรนเดอร์เซลล์แบบกําหนดเองสําหรับ:
    • แถบข้อมูลสําหรับค่าตัวเลข
    • ตัวบ่งชี้บูลีน
    • URL ที่คลิกได้
    • เซลล์ภาพที่มีการซ้อนทับด้วยกล่องไฟ
    • เซลล์หลายฟิลด์ เช่น ชื่อและบทบาทในคอลัมน์เดียว

คุณสามารถเพิ่มความสามารถ data grid อื่น ๆ ได้ แต่บางทีอาจต้องการวิศวกรรมเฉพาะมากขึ้น

การกำหนดธีม

ระบุข้อกําหนดแบรนด์หรือสไตล์ของตัวแทนโค้ดดิ้ง เช่น ชุดสี สไตล์มุม หรือฟอนต์ เทมเพลตจะเก็บสไตล์ที่ใช้ร่วมกันไว้ในที่เดียว เพื่อเปลี่ยนการไหลไปยังการ์ด ปุ่ม แผนภูมิ ตารางข้อมูล และทูลทิป

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

สตริงรูปแบบ

กําหนดรูปแบบหนึ่งครั้งต่อคอลัมน์ผลลัพธ์ เทมเพลตนี้สามารถใช้สตริงรูปแบบโมเดลเชิงความหมายซ้ําข้ามแกนแผนภูมิ ทูลทิป ป้ายข้อมูล การ์ด และเซลล์กริดข้อมูล

ตัวอย่างเช่น การกําหนด 1500.5 รูปแบบเดียวจะแสดงเป็น $1,500.50 และ 0.25 แสดงเป็น 25% ที่ใดก็ตามที่ค่าเหล่านั้นปรากฏ

การตรวจสอบความถูกต้องของเบราว์เซอร์

ก่อนเผยแพร่แอป ให้ใช้กระบวนการตรวจสอบเบราว์เซอร์ของ Playwright ที่รวมมาเพื่อเปิดแอปในเบราว์เซอร์จริงและตรวจสอบ:

  • ภาพแสดงผลถูกต้อง
  • แผนภูมิไม่ได้ถูกตัดหรือบีบอัด
  • ข้อความอ่านได้
  • กริดข้อมูลจัดการกับการล้น
  • สถานะโหลด, ว่างเปล่า และสถานะข้อผิดพลาดสามารถใช้ได้
  • ตัวกรอง การไฮไลท์ข้าม และการจัดรูปแบบข้อมูลทํางานได้ตามปกติ
  • คอนโซลเบราว์เซอร์ไม่มีข้อผิดพลาดที่ไม่คาดคิด

เวิร์กโฟลว์นี้ตรวจจับปัญหาการจัดวางและการแสดงผลก่อนที่ผู้ใช้จะเห็น การตรวจสอบเบราว์เซอร์ยืนยันพฤติกรรมของส่วนหน้า ทดสอบตัวเชื่อมต่อที่ติดตั้งแยกกับผู้ใช้ที่มีสิทธิ์เข้าถึงทั้งแอป Fabric และโมเดลเชิงความหมาย

ติดตั้งและตรวจสอบแอป

ปรับใช้การตั้งค่าแอปและตัวเชื่อมต่อ:

npx rayfin up

เปิดแอปที่ติดตั้งแล้วจากพอร์ทัล Fabric เข้าสู่ระบบ รันการโต้ตอบของผู้ใช้แต่ละครั้ง และเปรียบเทียบผลลัพธ์สําคัญกับโมเดลเชิงความหมาย

หากการค้นหาล้มเหลว:

  • ยืนยัน workspace และ semantic model item ID ใน rayfin.yml.
  • ยืนยันว่าการตั้งค่า SEMANTIC Model Execute Queries REST API tenant เปิดใช้งานแล้ว
  • ยืนยันว่าผู้ใช้มีสิทธิ์ Build และ Read บนโมเดลเชิงความหมาย
  • ตรวจสอบว่า DAX อ้างอิงตาราง คอลัมน์ และมาตรวัดที่มีอยู่แล้ว
  • ตรวจสอบหมวดหมู่ข้อผิดพลาดและข้อความของผลลัพธ์ของตัวเชื่อมต่อ
  • ตรวจสอบคอนโซลเบราว์เซอร์สําหรับข้อผิดพลาดฝั่งไคลเอนต์

เนื้อหาที่เกี่ยวข้อง

  • อัปเดตล่าสุดเมื่อ