เชื่อมต่อฟังก์ชันกับทรัพยากรภายนอก

ฟังก์ชันที่ติดตั้งจะเรียกใช้ทรัพยากร Azure และ Fabric ภายนอกเป็นตัวตนของแอปโดยใช้การตรวจสอบสิทธิ์แอปพลิเคชัน ประกาศว่ากลุ่มเป้าหมายเป็นฟังก์ชันที่ต้องการ และใช้โทเค็นที่แพลตฟอร์มจัดให้และครอบคลุมทรัพยากรผ่าน ctx.Tokens.

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

Prerequisites

• แอป Fabric ที่ฟังก์ชันถูกเปิดใช้งานแล้ว สําหรับคําแนะนําการตั้งค่า ดูที่ การใช้ฟังก์ชันในแอป Fabric
• services.functions.auth.typeตั้งค่าเป็น application in rayfin/rayfin.yml สําหรับรายละเอียดการกําหนดค่า โปรดดูที่ การตรวจสอบสิทธิ์แอปพลิเคชัน
• ตัวตนของแอปให้สิทธิ์เข้าถึงทรัพยากรภายนอกแต่ละตัวที่โค้ดฟังก์ชันเรียกใช้

ประกาศการเชื่อมต่อภายนอก

ประกาศกลุ่มเป้าหมายใน RayfinContext คําอธิบายประกอบ แล้วอ่านโทเค็นที่มีขอบเขตจาก ctx.Tokens:

import {
  UserDataFunctions,
  AudienceType,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

const udf = new UserDataFunctions();

udf.func(
  'accessStorage',
  async (
    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
  ): Promise<string> => {
    const token: string = ctx.Tokens.Storage;
    // Use the token with the resource SDK or REST API.
    return 'ok';
  },
  [],
);

คําอธิบายประกอบคือคําประกาศ การระบุกลุ่มเป้าหมายใน RayfinContext<Schema, Audiences> จะลงทะเบียนการผูกพันการเชื่อมต่อ เก็บอาร์กิวเมนต์ที่สามของ udf.func() as []ไว้

ctx.Tokens ถูกจํากัดให้อยู่ในกลุ่มเป้าหมายที่คุณประกาศ กลุ่มเป้าหมายที่ไม่ได้ประกาศทําให้เกิดข้อผิดพลาดในการคอมไพล์:

async (
  ctx: RayfinContext<AppSchema, AudienceType.Sql | AudienceType.Storage>,
) => {
  const sqlToken: string = ctx.Tokens.Sql;
  const storageToken: string = ctx.Tokens.Storage;
};

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

ระบุอาร์กิวเมนต์สคีมา

RayfinContext เริ่มจากสคีมาแอปของคุณก่อน ใช้สคีมาเดียวกันที่คุณส่งข้อมูลไป RayfinClient<AppSchema> เพื่อให้ไคลเอนต์ข้อมูลยังคงพิมพ์อยู่เมื่อคุณเพิ่มกลุ่มเป้าหมาย:

async (ctx: RayfinContext<AppSchema, AudienceType.Sql>) => {
  const data = ctx.getDataClient();
  const token = ctx.Tokens.Sql;
};

หากฟังก์ชันต้องการ audience แต่ไม่เข้าถึงฐานข้อมูล Rayfin ให้ส่งสคีมาเริ่มต้นอย่างชัดเจน:

async (ctx: RayfinContext<Record<string, any>, AudienceType.Fabric>) => {
  const token = ctx.Tokens.Fabric;
};

กลุ่มผู้ชมที่รองรับ

AudienceType เป็นแหล่งข้อมูลความจริงสําหรับกลุ่มเป้าหมายที่ได้รับการสนับสนุน:

แหล่งข้อมูลภายนอก	AudienceType
Fabric lakehouse, คลังสินค้า, ฐานข้อมูล SQL ใน Fabric, ฐานข้อมูลแบบมิเรอร์ หรือ Azure SQL Database	Sql
Fabric OneLake files, Azure Blob Storage, Azure Table storage หรือ Azure Queue Storage	Storage
Microsoft Fabric REST API	Fabric
Azure AI Foundry	AzureAI
Azure DevOps	ADO

โมเดลเชิงความหมายของ Power BI ไม่มีให้ใช้ผ่าน ctx.Tokens. ใช้ตัว fabric-semanticmodel เชื่อมต่อแทน สําหรับคําแนะนําเกี่ยวกับตัวเชื่อมต่อ ดูที่ ข้อมูลเชื่อมต่อกับ Fabric

เข้าใจข้อมูลเมตาของการปรับใช้

อาร์กิวเมนต์ชนิดข้อมูลจะถูกลบก่อนที่ฟังก์ชันจะทํางาน ในระหว่าง npx rayfin up, คอมไพเลอร์ TypeScript จะแก้ไขกลุ่มเป้าหมายที่ประกาศและเขียนยูเนียนลงในเมตาดาต้าสําหรับการติดตั้ง worker ฟังก์ชันจะใช้ข้อมูลเมตานั้นเพื่อผูกการเชื่อมต่อ

ชื่อประเภทจะทํางานเมื่อโปรเจกต์ Functions มี tsconfig.json:

type SqlAccess = AudienceType.Sql;

async (ctx: RayfinContext<AppSchema, SqlAccess>) => {
  const token = ctx.Tokens.Sql;
};

ชอบค่าที่ตรงตัว AudienceType.X มากกว่า ถ้าโปรเจกต์ Functions ไม่มี tsconfig.json, CLI จะใช้คอมไพเลอร์ไม่ได้และจะอ่านไวยากรณ์คําอธิบายแทน ในโหมดนั้น นามแฝงจะเปลี่ยนเป็นชื่อของตัวเองแทนที่จะเป็นกลุ่มเป้าหมายที่มันเป็นตัวแทน ให้ถือว่าคําเตือน CLI เกี่ยวกับ fallback นี้เป็นข้อผิดพลาดที่ต้องแก้ไข

พารามิเตอร์บริบทต้องมีคําอธิบายประกอบอย่างชัดเจนRayfinContext<...> การสร้างประเภทจะระบุพารามิเตอร์บริบทผ่านคําอธิบายประกอบนี้ หากไม่มีพารามิเตอร์นี้ พารามิเตอร์จะถูกปฏิบัติเป็นพารามิเตอร์ request-body

มอบสิทธิ์ทรัพยากร

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

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

เก็บโทเค็นทรัพยากรไว้บนเซิร์ฟเวอร์ อย่าส่งคืนผลลัพธ์เป็นฟังก์ชันหรือส่งไปยังส่วนหน้า

การลงชื่อเข้าใช้แอปและการอนุญาตให้เรียกใช้ฟังก์ชันนั้นแยกจากการเข้าถึงทรัพยากรภายนอกของตัวตนแอป

ตัวตนฐานข้อมูล Rayfin

ฐานข้อมูล Rayfin ใช้เส้นทางการตรวจสอบสิทธิ์แยกต่างหาก ctx.getDataClient() ใช้โทเค็น Rayfin ของการเรียกใช้งาน ดังนั้นการเข้าถึงฐานข้อมูลจะรักษาตัวตนและสิทธิ์ฐานข้อมูลของผู้โทรไว้ การตรวจสอบสิทธิ์แอปพลิเคชันสําหรับฟังก์ชันจะไม่สลับการเข้าถึงฐานข้อมูล Rayfin ไปยังตัวตนของแอปพลิเคชัน

ใช้โทเค็นกับ Azure SDK

ไคลเอนต์ Azure SDK หลายรายคาดหวัง TokenCredential token string แทนที่จะเป็น raw token string กําหนดอะแดปเตอร์ที่คืนโทเค็นจากบริบท:

import type { TokenCredential, AccessToken } from '@azure/identity';

class ContextTokenCredential implements TokenCredential {
  constructor(private readonly token: string) {}

  async getToken(): Promise<AccessToken> {
    return {
      token: this.token,
      expiresOnTimestamp: Date.now() + 3600_000,
    };
  }
}

ส่ง new ContextTokenCredential(ctx.Tokens.Storage) หรือโทเค็นที่ประกาศไว้ที่เหมาะสมให้กับไคลเอนต์ SDK ที่ต้องการข้อมูลรับรอง ติดตั้งแพ็กเกจ resource SDK ใน rayfin/functions/package.json, ไม่ใช่ใน project root

พัฒนาในพื้นที่

npx rayfin devและnpx rayfin dev functions applyเริ่มต้นโฮสต์ ฟังก์ชัน Azure Core Tools ในเครื่อง ในโฮสต์ Functions ภายในเครื่อง โทเค็นทรัพยากรภายนอกจะใช้ตัวตนและสิทธิ์ของบัญชีที่ตัวสร้างแอปใช้ในการลงชื่อเข้าใช้

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

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

• ใช้ฟังก์ชันในแอป Fabric
• เชื่อมต่อกับข้อมูล Fabric
• จัดการความลับของฟังก์ชัน
• ปรับใช้แอป Fabric เป็น Fabric