Hubungkan Fungsi ke sumber daya eksternal

Fungsi yang diterapkan memanggil sumber daya Azure dan Fabric eksternal menggunakan identitas aplikasi melalui autentikasi aplikasi. Nyatakan audiens yang dibutuhkan oleh suatu fungsi, dan gunakan token bercakupan sumber daya yang disediakan platform melalui ctx.Tokens.

Login CLI pengembang dan penemuan endpoint saat pembuatan terpisah dari akses runtime yang telah didistribusikan. Verifikasi izin identitas aplikasi yang telah diterapkan bahkan ketika pengembang dapat mengakses sumber daya tersebut.

Prasyarat

  • Aplikasi Fabric dengan Functions yang sudah diinisialisasi. Untuk petunjuk pengaturan, lihat Gunakan Fungsi di Fabric Apps.
  • services.functions.auth.type diatur ke application di rayfin/rayfin.yml. Untuk detail konfigurasi, lihat Autentikasi aplikasi.
  • Identitas aplikasi memberikan akses ke setiap sumber daya eksternal yang dipanggil oleh kode Fungsi.

Deklarasikan koneksi eksternal

Deklarasikan audiens dalam anotasi RayfinContext, lalu baca token yang dicakup dari 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';
  },
  [],
);

Anotasi adalah deklarasi. Mencantumkan audiens dalam RayfinContext<Schema, Audiences> akan mendaftarkan pengikatan koneksi. Pertahankan argumen ketiga dari udf.func() sebagai [].

ctx.Tokens dibatasi pada audiens yang Anda tentukan. Audiens yang tidak dideklarasikan menyebabkan kesalahan kompilasi:

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

Nilai token memiliki tipe tersebut string . Mendeklarasikan audiens akan mendaftarkan pengikatannya, tetapi tidak menjamin ketersediaan token atau akses ke sumber daya. Jika host tidak menyediakan token yang dideklarasikan, membaca ctx.Tokens propertinya akan memicu kesalahan.

Tentukan argumen skema

RayfinContext Ambil skema aplikasi Anda terlebih dahulu. Gunakan skema yang sama seperti yang Anda teruskan ke RayfinClient<AppSchema> agar klien data tetap memiliki tipe saat Anda menambahkan audiens:

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

Jika sebuah fungsi membutuhkan audiens tetapi tidak mengakses Rayfin DB, berikan skema default secara eksplisit:

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

Audiens yang didukung

AudienceType adalah sumber kebenaran bagi audiens yang didukung:

Sumber eksternal AudienceType
Fabric lakehouse, gudang data, database SQL di Fabric, database yang dicerminkan, atau Azure SQL Database Sql
file Fabric OneLake, Azure Blob Storage, Azure Table storage, atau Azure Queue Storage Storage
API Microsoft Fabric REST Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Model semantik Power BI tidak tersedia melalui ctx.Tokens. Gunakan fabric-semanticmodel konektor sebagai gantinya. Untuk panduan konektor, lihat Menyambungkan ke data Fabric.

Memahami metadata penyebaran

Argumen tipe dihapus sebelum fungsi dijalankan. Selama npx rayfin up, kompiler TypeScript menentukan audien yang dideklarasikan dan menulis union ke dalam metadata penerapan. Pekerja Functions menggunakan metadata tersebut untuk mengikat koneksi.

Alias jenis berfungsi jika proyek Functions memiliki sebuah tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Utamakan nilai literal AudienceType.X. Jika proyek Functions tidak memiliki tsconfig.json, CLI tidak dapat menggunakan kompilator dan sebagai gantinya membaca sintaks anotasi. Dalam mode itu, alias beralih ke namanya sendiri, bukan audiens yang diwakilinya. Anggap peringatan CLI tentang mekanisme fallback ini sebagai kesalahan yang perlu diperbaiki.

Parameter konteks harus memiliki anotasi eksplisit RayfinContext<...> . Type generation mengidentifikasi parameter konteks melalui anotasi ini. Tanpa itu, parameter diperlakukan sebagai parameter isi permintaan.

Berikan izin sumber daya

Untuk aplikasi Fabric saat ini, identitas aplikasi adalah pemilik item aplikasi Fabric. Koneksi eksternal menggunakan identitas ini dan izinnya, bukan identitas atau izin pengguna aplikasi yang memanggil fungsi tersebut.

Berikan kepada identitas aplikasi izin yang diperlukan oleh setiap sumber daya dan API yang dipanggil oleh kode Functions. Mendeklarasikan audiens dan menerapkan Fungsi mendaftarkan token binding tetapi tidak memberikan izin pada sumber daya target.

Simpan token sumber daya di server. Jangan pernah mengembalikannya sebagai hasil fungsi atau mengirimkannya ke frontend.

Masuk aplikasi dan otorisasi untuk memanggil fungsi terpisah dari akses identitas aplikasi ke sumber daya eksternal.

Identitas Rayfin DB

Rayfin DB menggunakan jalur autentikasi terpisah. ctx.getDataClient() menggunakan token Rayfin milik pemanggilan, sehingga akses basis data mempertahankan identitas pemanggil dan izin basis datanya. Autentikasi aplikasi untuk Functions tidak mengalihkan akses Rayfin DB ke identitas aplikasi.

Gunakan token dengan Azure SDK

Banyak klien Azure SDK mengharapkan TokenCredential alih-alih string token mentah. Definisikan adaptor yang mengembalikan token dari konteks:

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,
    };
  }
}

Pass new ContextTokenCredential(ctx.Tokens.Storage) atau token yang dideklarasikan sesuai ke klien SDK yang memerlukan kredensial. Instal paket SDK sumber daya di rayfin/functions/package.json, bukan di root proyek.

Kembangkan secara lokal

npx rayfin dev dan npx rayfin dev functions apply memulai host lokal Azure Functions Core Tools. Di host Functions lokal, token sumber daya eksternal menggunakan identitas dan izin akun yang digunakan pembuat aplikasi untuk masuk.

Fungsi yang di-deploy justru menggunakan identitas aplikasi. Panggilan lokal yang berhasil tidak membuktikan bahwa identitas aplikasi yang dideploy memiliki izin untuk mengakses sumber daya tersebut. Uji fungsi yang telah di-deploy setelah memberikan izin yang diperlukan kepada identitas aplikasi.

Konten terkait

  • Terakhir diperbarui pada