Membuat dan menyebarkan aplikasi satu halaman di Power Pages

Power Pages mendukung integrasi kode aplikasi halaman tunggal (SPA) yang dibuat dengan alat yang dibantu AI generasi berikutnya, seperti GitHub Copilot. Kemampuan ini memungkinkan pengembang menghadirkan pengalaman front-end modern berbasis komponen ke dalam Power Pages dengan menggunakan bahasa alami sebagai antarmuka pengodean.

Dengan membimbing, menguji, dan menyempurnakan kode yang dihasilkan AI, pembuat dapat mengalihkan fokus mereka dari tugas implementasi berulang ke orkestrasi tingkat yang lebih tinggi. Ini memberdayakan pengembangan yang lebih intuitif dan kreatif sekaligus mempertahankan kualitas dan standar tingkat perusahaan.

Artikel ini menunjukkan cara:

Buat dan siapkan proyek SPA untuk Power Pages dengan menggunakan Power Platform CLI (PAC CLI).
Unggah dan unduh aset kode ke dan dari situs Power Pages Anda.
Menyiapkan struktur proyek yang aman dan dapat dipelihara.
Pelajari perbedaan utama antara implementasi Power Pages berbasis SPA dan tradisional.

Catatan

Situs SPA adalah situs Power Pages yang berjalan sepenuhnya di browser pengguna (penyajian sisi klien). Tidak seperti situs Power Pages tradisional, situs SPA hanya dikelola melalui kode sumber dan alat antarmuka baris perintah (CLI).
Tidak didukung integrasi Power Platform Git untuk situs web Aplikasi Halaman Tunggal (SPA) di Power Pages.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Lingkungan Power Pages dengan hak istimewa administrator.
Power Platform CLI (PAC CLI) versi 1.44.x atau yang lebih baru diinstal dan diautentikasi.
Situs Power Pages pada versi 9.7.4.x atau yang lebih baru.
Izinkan unggahan file JavaScript di lingkungan Dataverse.
Repositori Git lokal dengan proyek front-end kustom Anda, seperti React, Angular, atau Vue.

Perbolehkan unggahan file JavaScript

Secara default, beberapa lingkungan Dataverse memblokir pengunggahan file JavaScript (). Jika Anda mengalami kesalahan "Impor gagal: Lampiran bukan jenis yang valid atau terlalu besar. Ini tidak dapat diunggah atau diunduh.", perbarui pengaturan lingkungan Anda untuk mengizinkan jenis file ini.

Untuk menyesuaikan pengaturan di pusat admin Power Platform untuk lingkungan, ikuti langkah-langkah ini:

Masuk ke pusat admin Power Platform.
Di panel navigasi, pilih Kelola.
Di panel Kelola, pilih Lingkungan.
Pilih lingkungan.
Pilih Pengaturan di bilah perintah.
Luaskan Produk, lalu pilih Privasi + Keamanan.
Di bagian Lampiran yang Diblokir , hapus dari daftar ekstensi file.
Pilih Simpan.

Membuat dan menyebarkan situs SPA

situs Power Pages SPA dikelola menggunakan perintah PAC CLI upload-code-site dan download-code-site. Setelah Anda mengunggah situs, situs tersebut muncul di Power Pages dalam daftar situs Inactive. Aktifkan situs untuk membuatnya tersedia bagi pengguna.

Mengunggah situs SPA

Gunakan perintah pac pages upload-code-site untuk mengunggah sumber lokal dan aset yang dikompilasi ke lingkungan Power Pages Anda.

Sintaks

pac pages upload-code-site `
  --rootPath <local-source-folder> `
  [--compiledPath <build-output-folder>] `
  [--siteName <site-display-name>]

Parameter

Parameter	Alias	Wajib	Deskripsi
`--rootPath`	`-rp`	Ya	Folder lokal yang berisi file sumber situs Anda
`--compiledPath`	`-cp`	Tidak	Jalur ke aset yang dikompilasi, seperti React
`--siteName`	`-sn`	Tidak	Nama tampilan untuk situs Power Pages Anda

Contoh

pac pages upload-code-site `
  --rootPath "../your-project" `
  --compiledPath "./build" `
  --siteName "Contoso Code Site"

Jika Anda tidak memiliki proyek yang sudah ada, coba implementasi sampel situs SPA menggunakan React, Angular, dan Vue.

Menentukan parameter unggahan dengan

Sesuaikan perilaku perintah dengan menyertakan file di situs Anda. Tempatkan file konfigurasi ini di folder root situs. Saat Anda menggunakan upload situs berbasis konfigurasi, jalankan perintah hanya dengan parameter . Perintah ini secara otomatis membaca nilai lain, seperti jalur aset yang dikompilasi dan nama tampilan situs, dari file . Jika Anda memberikan argumen baris perintah dan nilai konfigurasi, argumen baris perintah akan diutamakan.

Sampel :

{
  "siteName": "Contoso Bank",
  "defaultLandingPage": "index.html",
  "compiledPath": "C:\\PowerPages\\your-project\\dist"
}

Unduh situs SPA

Gunakan perintah pac pages download-code-site untuk mengunduh kode situs yang ada ke direktori lokal untuk tujuan pengeditan atau pencadangan.

Sintaks

pac pages download-code-site `
  [--environment <env-url-or-guid>] `
  --path <local-target-folder> `
  --webSiteId <site-guid> `
  [--overwrite]

Parameter

Parameter	Alias	Wajib	Deskripsi
`--environment`	`-env`	Tidak	Lingkungan Dataverse (GUID atau URL lengkap). Default ke profil autentikasi aktif Anda
`--path`	`-p`	Ya	Direktori lokal untuk mengunduh kode situs
`--webSiteId`	`-id`	Ya	GUID rekaman situs web di situs SPA Power Pages
`--overwrite`	`-o`	Tidak	Timpa file yang ada di direktori target jika ada

Contoh

pac pages download-code-site `
  --environment "https://contoso.crm.dynamics.com" `
  --path "./downloaded-site" `
  --webSiteId "11112222-bbbb-3333-cccc-4444dddd5555" `
  --overwrite

Aktifkan dan uji situs Anda

Buka Power Pages.
Pilih Situs tidak aktif, temukan situs Anda, dan pilih Aktifkan kembali.
Saat situs aktif, buka URL situs Anda untuk memeriksa penyebaran.

Tip

Setiap perintah yang lebih baru secara otomatis memperbarui situs aktif.

Struktur dan konfigurasi proyek

Tata letak proyek yang konsisten membantu memastikan perilaku upload yang benar.

/your-project
│
├─ src/                       ← Your source code, like React components
├─ build/                     ← Compiled assets, output of the `npm run build` command
├─ powerpages.config.json     ← Optional CLI configuration file
└─ README.md

Gunakan file opsional untuk menyesuaikan cara kerja perintah .

Otentikasi dan otorisasi

Situs SPA Power Pages menggunakan model keamanan yang sama seperti situs Power Pages tradisional.

Mengonfigurasi penyedia identitas

Buka Power Pages.
Temukan situs Anda dan pilih Edit.
PilihPenyedia Identitas.
Tambahkan atau siapkan penyedia identitas, seperti Microsoft Entra ID.
Setiap situs baru secara otomatis memiliki penyedia Microsoft Entra ID default.

Akses konteks pengguna dalam kode

Dapatkan metadata autentikasi pada klien:

URL Otoritas:

Otoritas atau URL masuk untuk Microsoft Entra ID adalah:
```
https://login.windows.net/<tenantId>
```
Temukan URL Authority untuk penyedia identitas lain yang dikonfigurasi dengan membuka Power Pages><your site>>Keamanan>Pengaturan konfigurasi penyedia identitas>.

Rincian Pengguna:

window["Microsoft"].Dynamic365.Portal.User

Alur React sampel

import { IconButton, Tooltip } from '@mui/material';
import {
    Login,
    Logout
} from '@mui/icons-material';
import React from 'react';
export const AuthButton = () => {
    const username = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.userName ?? "";
    const firstName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.firstName ?? "";
    const lastName = (window as any)["Microsoft"]?.Dynamic365?.Portal?.User?.lastName ?? "";
    const tenantId = (window as any)["Microsoft"]?.Dynamic365?.Portal?.tenant ?? "";
    const isAuthenticated = username !== "";
    const [token, setToken] = React.useState<string>("");

    React.useEffect(() => {
        const fetchAntiForgeryToken = async (): Promise<string> => {
            try {
                const tokenEndpoint = "/_layout/tokenhtml";

                const response = await fetch(tokenEndpoint, {});

                if (response.status !== 200) {
                    throw new Error(`Failed to fetch token: ${response.status}`);
                }

                const tokenResponse = await response.text();                
                const valueString = 'value="';
                const terminalString = '" />';
                const valueIndex = tokenResponse.indexOf(valueString);

                if (valueIndex === -1) {
                    throw new Error('Token not found in response');
                }

                const requestVerificationToken = tokenResponse.substring(
                    valueIndex + valueString.length,
                    tokenResponse.indexOf(terminalString, valueIndex)
                );

                return requestVerificationToken || '';
            } catch (error) {
                console.warn('[Impersonation] Failed to fetch anti-forgery token:', error);
                return '';
            }
        };

        const getToken = async () => {
            try {
                const token = await fetchAntiForgeryToken();
                setToken(token);
            } catch (error) {
                console.error('Error fetching token:', error);
            }
        };
        getToken();
    }, []);

    return (
        <div className="flex items-center gap-4">
            {isAuthenticated ? (
                <>
                    <span className="text-sm">Welcome {firstName + " " + lastName}</span>
                    <Tooltip title="Logout">
                        <IconButton color="primary" onClick={() => window.location.href = "/Account/Login/LogOff?returnUrl=%2F"}>
                            <Logout />
                        </IconButton>
                    </Tooltip>
                </>
            ) : (
                <form action="/Account/Login/ExternalLogin" method="post">
                    <input name="__RequestVerificationToken" type="hidden" value={token} />
                    <Tooltip title="Login">
                        <IconButton name="provider" type="submit" color="primary" value={`https://login.windows.net/${tenantId}/`}>
                            <Login />
                        </IconButton>
                    </Tooltip>
                </form>
            )}
        </div>
    );
};

Menggunakan API Web Power Pages

Pengembang dapat memanfaatkan API Web Power Pages untuk memuat konten ke UI atau untuk membuat, memperbarui, dan menghapus rekaman. Sebelum menggunakan API ini, pastikan bahwa API Web yang diperlukan diaktifkan dan izin tabel dan peran web yang sesuai dikonfigurasi dengan benar.


// Create query to get all cards from Dataverse
const fetchCards = async () => {
    const response = await fetch("/_api/cr7ae_creditcardses");
    const data = await response.json();
    const cards = data.value;
    const returnData = [];

    // Loop through the cards and get the name and id of each card
    for (let i = 0; i < cards.length; i++) {
        const card = cards[i];
        const cardName = card.cr7ae_name;
        const cardId = card.cr7ae_creditcardsid;
        const features = card.cr7ae_features
            ?.split(',')
            .map((feature: string) => feature.trim());
        const type = card.cr7ae_type;
        const image = card.cr7ae_image;
        const category = card.cr7ae_category
            ?.split(',')
            .map((cat: string) => cat.trim());
        
        // ...additional processing/pushing to returnData...
    }

    return returnData;
};

Siapkan pengembangan lokal dengan mengaktifkan panggilan API Web dari localhost menggunakan autentikasi Microsoft Entra ID

Pengembang membutuhkan siklus iterasi yang lebih cepat, penelusuran kesalahan lokal, dan kemampuan pemuatan ulang panas saat membangun aplikasi. SPA mendukung alur kerja ini dengan mengaktifkan panggilan API Web aman dari localhost menggunakan autentikasi Microsoft Entra ID (Azure AD) v1.

Pengaturan ini memungkinkan Anda:

Jalankan aplikasi Anda secara lokal dengan dukungan autentikasi penuh.
Gunakan alat pengembangan modern seperti Vite untuk pemutakhiran langsung dan umpan balik cepat.
Hindari masalah CORS saat memanggil API Web Power Pages.
Mempercepat pengembangan tanpa menyebarkan perubahan ke portal.

Konfigurasi ini memungkinkan pengalaman pengembangan lokal yang produktif untuk SPA, memungkinkan pengembang untuk membangun, menguji, dan melakukan iterasi dengan cepat dengan akses API penuh dan dukungan autentikasi.

Penting

Gunakan hanya endpoint Microsoft Entra v1 untuk autentikasi.
Autentikasi pembawa hanya didukung di portal versi 9.7.6.6 atau yang lebih baru.
Terapkan pengaturan ini hanya di lingkungan pengembangan.

Langkah-langkah konfigurasi

Mengaktifkan autentikasi SPA
1. Di https://portal.azure.com, buka aplikasi Microsoft Entra yang terdaftar untuk portal Anda.
2. Aktifkan autentikasi Aplikasi Halaman Tunggal (SPA ).
3. Tambahkan sebagai URI pengalihan menggunakan konfigurasi platform aplikasi satu halaman. Lihat Cara menambahkan URI pengalihan di aplikasi Anda untuk detail selengkapnya.
  - Alihkan URI: .

Menambahkan pengaturan situs

Tambahkan pengaturan situs di Power Pages:

Authentication/BearerAuthentication/Enabled = true
Authentication/BearerAuthentication/Protocol = OpenIdConnect
Authentication/BearerAuthentication/Provider = AzureAD

Gunakan ADAL.js untuk masuk
- Terapkan login sisi klien menggunakan ADAL.js.
Catatan

MSAL.js tidak kompatibel karena Power Pages menggunakan titik akhir Microsoft Entra v1, sedangkan MSAL menggunakan v2. Format pengeluar sertifikat berbeda di antara versi.
Tambahkan header otorisasi
- Sertakan header ini di semua permintaan API Web:
```
Authorization: Bearer <id_token>
```
Mengatur visibilitas situs ke Publik
- Pengaturan ini memungkinkan akses situs untuk tujuan pengembangan dan pengujian.

Mengonfigurasi proksi pengembangan

Jika Anda menggunakan Vite, tambahkan ini ke agar terhindar dari masalah CORS.

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/_api': {
        target: 'https://site-foo.powerappsportals.com',
        changeOrigin: true,
        secure: true
      }
    }
  }
});

Perbedaan dari situs Power Pages yang ada

Tabel berikut ini meringkas perbedaan utama antara situs SPA yang dibuat dengan fitur ini dan situs Power Pages tradisional:

Fitur	Perilaku situs SPA
Refresh sisi server	Selalu mengembalikan halaman root situs, dan router sisi klien merender sub-rute.
Konflik rute	Rute sisi klien diutamakan, dan refresh keras kembali ke root.
Ruang kerja halaman	Ruang kerja halaman tidak didukung. Gunakan perutean klien dan halaman situs klien. Untuk keamanan tingkat halaman, periksa peran web yang ditetapkan dengan objek pengguna global, dan render UI secara kondisional.
Ruang kerja gaya	Penataan gaya dengan ruang kerja gaya tidak didukung. Gunakan gaya kerangka kerja Anda, seperti CSS, CSS-in-JS, atau kelas utilitas.
Pelokalan	Dukungan satu bahasa. Terapkan pemuatan sumber daya sisi klien.
Template liquid	Kode Liquid dan template Liquid tidak didukung. Akses data dengan menggunakan mesin templat kerangka kerja dan API Web Anda.

FAQ

Dukungan apa yang tersedia untuk pengujian unit dan integrasi?

Saat ini, tidak ada dukungan bawaan untuk pengujian unit dan integrasi. Pembuat harus menulis dan menjalankan pengujian ini secara lokal atau dalam alur CI/CD mereka.

Apakah ada dukungan untuk integrasi Power Fx menggunakan WebAssembly?

Kemampuan ini saat ini tidak didukung.

Apakah kode sumber tersedia di Power Pages?

Saat ini, pembuat dapat membangun situs web menggunakan TypeScript atau Agen GitHub Copilot. File JavaScript dan CSS yang dikompilasi dapat diakses dan dapat diedit di Visual Studio Code. Namun, pengeditan file HTML secara langsung dan ekstensif saat ini tidak didukung.

Bisakah saya membuat komponen secara eksternal menggunakan fitur ini dan membawanya ke situs Power Pages?

Tidak, Anda tidak dapat membawa komponen yang dihasilkan secara eksternal ke situs Power Pages yang ada menggunakan fitur ini.

Bisakah saya menambahkan komponen bawaan seperti daftar dan formulir?

Menambahkan komponen siap pakai seperti daftar dan formulir saat ini tidak didukung. Namun, Anda dapat membuat formulir dan daftar kustom menggunakan kerangka kerja React dan API Web.

Bagaimana cara kerja kontrol sumber?

Pengembang dapat menggunakan integrasi Git Power Platform untuk kontrol sumber. Namun, hanya file web yang dikompilasi yang ditambahkan ke repositori, bukan kode sumber lengkap.

Apakah situs-situs ini mendukung SEO?

Karena situs SPA dibangun dengan kerangka kerja React dan menggunakan rendering sisi klien, dukungan SEO terbatas.

Dukungan keamanan dan tata kelola Power Pages apa yang ditawarkan situs SPA?

Power Pages memberlakukan izin tabel dan peran web keamanan pada panggilan API Web, memastikan bahwa akses data selaras dengan peran pengguna. Gunakan objek untuk mengambil properti pengguna dasar dan menyesuaikan pengalaman berdasarkan persona pengguna.

Selain itu, situs SPA mendukung:

Konfigurasi situs publik dan pribadi
Pengaturan tata kelola, termasuk kontrol atas akses data anonim
Konfigurasi penyedia autentikasi

Fitur-fitur ini membantu memastikan integrasi komponen kustom yang aman dan sesuai dalam Power Pages.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-07

Bagikan melalui

Membuat dan menyebarkan aplikasi satu halaman di Power Pages

Prasyarat

Perbolehkan unggahan file JavaScript

Membuat dan menyebarkan situs SPA

Mengunggah situs SPA

Sintaks

Parameter

Contoh

Menentukan parameter unggahan dengan

Unduh situs SPA

Sintaks

Parameter

Contoh

Aktifkan dan uji situs Anda

Struktur dan konfigurasi proyek

Otentikasi dan otorisasi

Mengonfigurasi penyedia identitas

Akses konteks pengguna dalam kode

Alur React sampel

Menggunakan API Web Power Pages

Siapkan pengembangan lokal dengan mengaktifkan panggilan API Web dari localhost menggunakan autentikasi Microsoft Entra ID

Langkah-langkah konfigurasi

Perbedaan dari situs Power Pages yang ada

FAQ

Dukungan apa yang tersedia untuk pengujian unit dan integrasi?

Apakah ada dukungan untuk integrasi Power Fx menggunakan WebAssembly?

Apakah kode sumber tersedia di Power Pages?

Bisakah saya membuat komponen secara eksternal menggunakan fitur ini dan membawanya ke situs Power Pages?

Bisakah saya menambahkan komponen bawaan seperti daftar dan formulir?

Bagaimana cara kerja kontrol sumber?

Apakah situs-situs ini mendukung SEO?

Dukungan keamanan dan tata kelola Power Pages apa yang ditawarkan situs SPA?

Informasi terkait

Saran dan Komentar

Sumber Daya Tambahan: