การกําหนดค่าการติดตั้งแอปเทมเพลตแบบอัตโนมัติ

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

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

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

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

สิ่งที่พวกเขาต้องทําคือเลือก ติดตั้ง และรับรองความถูกต้องเทียบกับแหล่งข้อมูลของพวกเขา และพวกเขาก็พร้อมแล้ว!

ประสบการณ์ของลูกค้าแสดงเป็นภาพประกอบไว้ที่นี่

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

โฟลว์พื้นฐาน

โฟลว์พื้นฐานของการทําให้การกําหนดค่าการติดตั้งแอปเทมเพลตเป็นแบบอัตโนมัติเป็นดังนี้:

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

2. ISV ได้รับ โทเค็นเฉพาะ แอปตาม องค์ประกอบหลักของบริการ (โทเค็นเฉพาะแอป) ที่ลงทะเบียนในผู้เช่าของ ISV

3. ด้วยการใช้ Power BI REST API ISV จะสร้าง ตั๋วการติดตั้งซึ่งมีการกําหนดค่าพารามิเตอร์เฉพาะของผู้ใช้ตามที่ ISV เตรียมไว้

4. ISV เปลี่ยนเส้นทางผู้ใช้ไปยัง Power BI โดยใช้ POST วิธีการเปลี่ยนเส้นทางที่มีตั๋วการติดตั้ง

5. ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังบัญชี Power BI ของพวกเขาด้วยตั๋วการติดตั้งและได้รับพร้อมท์แจ้งให้ติดตั้งแอปเทมเพลต เมื่อผู้ใช้เลือก ติดตั้ง แอปเทมเพลตจะถูกติดตั้งสําหรับพวกเขา

หมายเหตุ

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

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

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

• สิทธิ์การใช้งาน Power BI Pro หากคุณยังไม่ได้ลงทะเบียน Power BI Pro ให้ ลงทะเบียนรุ่นทดลองใช้ ฟรีก่อนที่คุณจะเริ่มต้น

• ตั้งค่าผู้เช่า Microsoft Entra ของคุณเอง สําหรับคําแนะนําเกี่ยวกับวิธีการตั้งค่า โปรดดู สร้างผู้เช่า Microsoft Entra

• องค์ประกอบ หลักของบริการ (โทเค็นเฉพาะแอป) ที่ลงทะเบียนในผู้เช่าก่อนหน้า สําหรับข้อมูลเพิ่มเติม โปรดดู ฝังเนื้อหา Power BI ด้วยองค์ประกอบหลักของบริการและข้อมูลลับของแอปพลิเคชัน ตรวจสอบให้แน่ใจว่าได้ลงทะเบียนแอปพลิเคชันเป็น แอปเว็บแอปพลิเคชัน ฝั่งเซิร์ฟเวอร์ คุณลงทะเบียนแอปพลิเคชันเว็บฝั่งเซิร์ฟเวอร์เพื่อสร้างความลับของแอปพลิเคชัน จากขั้นตอนนี้ คุณจําเป็นต้องบันทึก ID แอปพลิเคชัน (ID ไคลเอ็นต์) และข้อมูลลับของแอปพลิเคชัน (ข้อมูลลับของไคลเอ็นต์) สําหรับขั้นตอนในภายหลัง

• แอปเทมเพลตที่กําหนดพารามิเตอร์ที่พร้อมสําหรับการติดตั้ง ต้องสร้างแอปเทมเพลตในผู้เช่าเดียวกันกับที่คุณลงทะเบียนแอปพลิเคชันของคุณในรหัส Microsoft Entra สําหรับข้อมูลเพิ่มเติม ดูเคล็ดลับแอปเทมเพลตหรือสร้างแอปแม่แบบใน Power BI จากแอปเทมเพลต คุณต้องจดข้อมูลต่อไปนี้สําหรับขั้นตอนถัดไป:

  • App ID, Package Key และ Owner ID ตามที่ปรากฏใน URL การติดตั้งในตอนท้ายของกระบวนการ กําหนดคุณสมบัติของแอป เทมเพลตเมื่อสร้างแอปขึ้นแล้ว คุณยังสามารถรับลิงก์เดียวกันได้โดยการเลือกรับลิงก์ในบานหน้าต่างการจัดการนําไปใช้งานจริงของแอปเทมเพลต
  • ชื่อ พารามิเตอร์ตามที่กําหนดไว้ในแบบจําลองความหมายของแอปเทมเพลต ชื่อพารามิเตอร์เป็นสตริงที่คํานึงถึงตัวพิมพ์เล็กและใหญ่ และยังสามารถดึงชื่อดังกล่าวได้จากแท็บการตั้งค่าพารามิเตอร์เมื่อคุณกําหนดคุณสมบัติของแอปเทมเพลตหรือจากการตั้งค่าแบบจําลองความหมายใน Power BI

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

  หมายเหตุ

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

ขั้นตอนหลักและ API

ขั้นตอนหลักสําหรับการทําให้การกําหนดค่าการติดตั้งแอปเทมเพลตและ API ที่คุณต้องการเป็นแบบอัตโนมัติมีอธิบายไว้ในส่วนต่อไปนี้ แม้ว่าขั้นตอนส่วนใหญ่จะดําเนินการด้วย Power BI REST API แต่ตัวอย่างโค้ดที่อธิบายที่นี้ใช้ .NET SDK

ขั้นตอนที่ 1: สร้างวัตถุไคลเอ็นต์ Power BI

การใช้ Power BI REST API ทําให้คุณต้องได้รับโทเค็นการเข้าถึงสําหรับองค์ประกอบหลักของบริการของคุณจากรหัส Microsoft Entra คุณจําเป็นต้องรับโทเค็นการเข้าถึง Microsoft Entra สําหรับแอปพลิเคชัน Power BI ของคุณก่อนที่คุณจะเรียกใช้ Power BI REST API เมื่อต้องสร้าง Power BI client ด้วยโทเค็นการเข้าถึง คุณจําเป็นต้องสร้างออบเจ็กต์ไคลเอ็นต์ Power BI ซึ่งช่วยให้คุณสามารถโต้ตอบกับ Power BI REST APIs ได้ คุณสร้างวัตถุไคลเอ็นต์ Power BI ได้โดยการคลุม AccessToken ด้วยวัตถุ Microsoft.Rest.TokenCredentials

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Microsoft.Rest;
using Microsoft.PowerBI.Api.V2;

var tokenCredentials = new TokenCredentials(authenticationResult.AccessToken, "Bearer");

// Create a Power BI client object. It's used to call Power BI APIs.
using (var client = new PowerBIClient(new Uri(ApiUrl), tokenCredentials))
{
    // Your code goes here.
}

ขั้นตอนที่ 2: สร้างตั๋วการติดตั้ง

สร้างตั๋วการติดตั้งซึ่งใช้เมื่อคุณเปลี่ยนเส้นทางผู้ใช้ของคุณไปยัง Power BI API ที่ใช้สําหรับการดําเนินการนี้คือ CreateInstallTicket API

• แอปเทมเพลต CreateInstallTicket

ตัวอย่างวิธีการสร้างตั๋วการติดตั้งสําหรับการติดตั้งและการกําหนดค่าแอปเทมเพลตสามารถดูได้จาก ไฟล์ InstallTemplateApp/InstallAppFunction.cs ใน แอปพลิเคชันตัวอย่าง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีการใช้ CreateInstallTicket REST API ของแอปเทมเพลต

using Microsoft.PowerBI.Api.V2;
using Microsoft.PowerBI.Api.V2.Models;

// Create Install Ticket Request.
InstallTicket ticketResponse = null;
var request = new CreateInstallTicketRequest()
{
    InstallDetails = new List<TemplateAppInstallDetails>()
    {
        new TemplateAppInstallDetails()
        {
            AppId = Guid.Parse(AppId),
            PackageKey = PackageKey,
            OwnerTenantId = Guid.Parse(OwnerId),
            Config = new TemplateAppConfigurationRequest()
            {
                Configuration = Parameters
                                    .GroupBy(p => p.Name)
                                    .ToDictionary(k => k.Key, k => k.Select(p => p.Value).Single())
            }
        }
    }
};

// Issue the request to the REST API using .NET SDK.
InstallTicket ticketResponse = await client.TemplateApps.CreateInstallTicketAsync(request);

ขั้นตอนที่ 3: เปลี่ยนเส้นทางผู้ใช้ไปยัง Power BI ด้วยตั๋ว

หลังจากที่คุณสร้างตั๋วการติดตั้งแล้ว คุณจะใช้ตั๋วดังกล่าวเพื่อเปลี่ยนเส้นทางผู้ใช้ของคุณไปยัง Power BI เพื่อดําเนินการติดตั้งและการกําหนดค่าแอปเทมเพลตต่อไป คุณใช้ POST วิธีการเปลี่ยนเส้นทางไปยัง URL การติดตั้งของแอปเทมเพลต ด้วยตั๋วการติดตั้งในเนื้อความของคําขอ

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

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

<html>
    <body onload='document.forms["form"].submit()'>
        <!-- form method is POST and action is the app install URL -->
        <form name='form' action='https://app.powerbi.com/....' method='post' enctype='application/json'>
            <!-- value should be the new install ticket -->
            <input type='hidden' name='ticket' value='H4sI....AAA='>
        </form>
    </body>
</html>

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

...
    return new ContentResult() { Content = RedirectWithData(redirectUrl, ticket.Ticket), ContentType = "text/html" };
}

...

public static string RedirectWithData(string url, string ticket)
{
    StringBuilder s = new StringBuilder();
    s.Append("<html>");
    s.AppendFormat("<body onload='document.forms[\"form\"].submit()'>");
    s.AppendFormat("<form name='form' action='{0}' method='post' enctype='application/json'>", url);
    s.AppendFormat("<input type='hidden' name='ticket' value='{0}' />", ticket);
    s.Append("</form></body></html>");
    return s.ToString();
}

หมายเหตุ

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

ขั้นตอนที่ 4: ย้ายการทํางานโดยอัตโนมัติของคุณไปยังการผลิต

เมื่อการทํางานโดยอัตโนมัติที่คุณออกแบบไว้พร้อมแล้ว อย่าลืมย้ายไปยังการผลิต

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

• ลองดูบทช่วยสอนของเรา ซึ่งใช้ Azure Function อย่างง่ายเพื่อทําให้การกําหนดค่าการติดตั้งแอปเทมเพลตเป็นไปโดยอัตโนมัติ
• มีคำถามเพิ่มเติมหรือไม่? ลองถามชุมชน Power BI ดู