ตัวอย่างตัวเชื่อมต่อ GitHub

ส่วนขยาย GitHub M แสดงวิธีการเพิ่มการสนับสนุนสําหรับโฟลว์การรับรองความถูกต้องโพรโทคอล OAuth 2.0 คุณสามารถเรียนรู้เพิ่มเติมเกี่ยวกับข้อมูลจําเพาะของโฟลว์การรับรองความถูกต้องของ GitHub บน ไซต์นักพัฒนา GitHub ได้

ก่อนที่คุณจะเริ่มสร้างส่วนขยาย M คุณต้องลงทะเบียนแอปใหม่บน GitHub และแทนที่ client_id ไฟล์ และ client_secret ด้วยค่าที่เหมาะสมสําหรับแอปของคุณ

หมายเหตุเกี่ยวกับปัญหาความเข้ากันได้ใน Visual Studio: Power Query SDK ใช้ตัวควบคุมที่ยึดตาม Internet Explorer เพื่อเปิดกล่องโต้ตอบ OAuth GitHub ได้ยกเลิกการสนับสนุนสําหรับเวอร์ชันของ IE ที่ใช้โดยตัวควบคุมนี้ ซึ่งจะป้องกันไม่ให้คุณดําเนินการขอสิทธิ์สําหรับคุณหากเรียกใช้จากภายใน Visual Studio ทางเลือกคือการโหลดส่วนขยายด้วย Power BI Desktop และทําโฟลว์ OAuth แรกให้เสร็จสิ้นที่นั่น หลังจากแอปพลิเคชันของคุณได้รับอนุญาตให้เข้าถึงบัญชีของคุณแล้ว การเข้าสู่ระบบที่ตามมาจะทํางานได้ดีจาก Visual Studio

OAuth และ Power BI

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

หมายเหตุ

เพื่ออนุญาตให้ Power BI รับและใช้ access_token คุณต้องระบุ URL เปลี่ยนเส้นทางเป็นhttps://oauth.powerbi.com/views/oauthredirect.html

เมื่อคุณระบุ URL นี้และ GitHub สําเร็จจะรับรองความถูกต้องและให้สิทธิ์ GitHub จะเปลี่ยนเส้นทางไปยังจุดสิ้นสุด oauthredirect ของ PowerBI เพื่อให้ Power BI สามารถดึงข้อมูล access_token และ refresh_token ได้

วิธีการลงทะเบียนแอป GitHub

ส่วนขยาย Power BI ของคุณต้องเข้าสู่ระบบ GitHub เมื่อต้องการเปิดใช้งานคุณต้องลงทะเบียนแอปพลิเคชัน OAuth ใหม่ด้วย GitHub ที่https://github.com/settings/applications/new

1. Application name: ใส่ชื่อสําหรับแอปพลิเคชันสําหรับส่วนขยาย M ของคุณ
2. Authorization callback URL: ป้อนhttps://oauth.powerbi.com/views/oauthredirect.html
3. Scope: ใน GitHub ตั้งค่าขอบเขตเป็นuser, repo

หมายเหตุ

แอปพลิเคชัน OAuth ที่ลงทะเบียนจะได้รับมอบหมาย ID ไคลเอ็นต์ และข้อมูลลับไคลเอ็นต์ ที่ไม่ซ้ํากัน ข้อมูลลับไคลเอ็นต์ไม่ควรแชร์ คุณจะได้รับ ID ไคลเอ็นต์และข้อมูลลับไคลเอ็นต์จากหน้าแอปพลิเคชัน GitHub อัปเดตไฟล์ในโครงการตัวเชื่อมต่อข้อมูลของคุณด้วย ID ไคลเอ็นต์ (client_id ไฟล์) และข้อมูลลับของไคลเอ็นต์ (client_secret ไฟล์)

วิธีใช้ GitHub OAuth

ตัวอย่างนี้จะแนะนําคุณผ่านขั้นตอนต่อไปนี้:

1. สร้างข้อกําหนดชนิดแหล่งข้อมูลที่ประกาศสนับสนุน OAuth
2. ระบุรายละเอียดดังนั้นกลไก M สามารถเริ่มต้นโฟลว์ OAuth (StartLogin)
3. แปลงรหัสที่ได้รับจาก GitHub เป็น access_token (FinishLogin และ TokenMethod)
4. กําหนดฟังก์ชันที่เข้าถึง GitHub API (GithubSample.Contents)

ขั้นตอนที่ 1 - สร้างข้อกําหนดของแหล่งข้อมูล

ตัวเชื่อมต่อข้อมูลเริ่มต้นด้วย ระเบียน ที่อธิบายส่วนขยาย รวมถึงชื่อที่ไม่ซ้ํากัน (ซึ่งเป็นชื่อของระเบียน) ชนิดการรับรองความถูกต้องที่ได้รับการสนับสนุน และชื่อที่แสดงที่เรียกง่าย (ป้ายชื่อ) สําหรับแหล่งข้อมูล เมื่อสนับสนุน OAuth ข้อกําหนดจะประกอบด้วยฟังก์ชันที่ใช้สัญญา OAuth ซึ่งในกรณีนี้คือ StartLogin และFinishLogin

//
// Data Source definition
//
GithubSample = [
    Authentication = [
        OAuth = [
            StartLogin = StartLogin,
            FinishLogin = FinishLogin
        ]
    ],
    Label = Extension.LoadString("DataSourceLabel")
];

ขั้นตอนที่ 2 - ให้รายละเอียดเพื่อให้กลไก M สามารถเริ่มต้นโฟลว์ OAuth ได้

โฟลว์ GitHub OAuth เริ่มต้นเมื่อคุณนําผู้ใช้ไปยัง https://github.com/login/oauth/authorize หน้า เพื่อให้ผู้ใช้เข้าสู่ระบบ คุณจําเป็นต้องระบุพารามิเตอร์คิวรีจํานวนหนึ่ง:

ชื่อ	ชนิด	คำอธิบาย
client_id	string	จำเป็นต้องใช้ ID ไคลเอ็นต์ที่คุณได้รับจาก GitHub เมื่อคุณลงทะเบียน
redirect_uri	string	URL ในแอปของคุณที่จะส่งผู้ใช้หลังจากการรับรองความถูกต้อง ดูรายละเอียดด้านล่างเกี่ยวกับ URL เปลี่ยนเส้นทาง สําหรับส่วนขยาย redirect_uri M ต้องเป็น "https://oauth.powerbi.com/views/oauthredirect.html"
ขอบเขต	string	รายการขอบเขตที่คั่นด้วยจุลภาค ถ้าไม่มี ขอบเขตเริ่มต้นจะเป็นรายการขอบเขตที่ว่างเปล่าสําหรับผู้ใช้ที่ไม่มีโทเค็นที่ถูกต้องสําหรับแอป สําหรับผู้ใช้ที่มีโทเค็นที่ถูกต้องสําหรับแอปอยู่แล้ว ผู้ใช้จะไม่แสดงหน้าการอนุญาต OAuth ที่มีรายการขอบเขต แต่ขั้นตอนนี้ของโฟลว์จะเสร็จสมบูรณ์โดยอัตโนมัติด้วยขอบเขตเดียวกันกับที่ใช้ครั้งล่าสุดที่ผู้ใช้ดําเนินการโฟลว์เสร็จสมบูรณ์
สถานะ	string	สตริงแบบสุ่มที่ไม่สามารถคาดเดาได้ ซึ่งถูกใช้เพื่อป้องกันการโจมตีจากข้ามไซต์

ส่วนย่อยของโค้ดต่อไปนี้อธิบายวิธีการใช้ StartLogin ฟังก์ชันเพื่อเริ่มโฟลว์การเข้าสู่ระบบ StartLoginฟังก์ชันจะใช้resourceUrlค่า , stateและdisplay ในฟังก์ชัน ให้สร้าง AuthorizeUrl ที่รวม URL ที่อนุญาต GitHub ด้วยพารามิเตอร์ต่อไปนี้:

• client_id: คุณได้รับ ID ไคลเอ็นต์หลังจากที่คุณลงทะเบียนส่วนขยายของคุณกับ GitHub จากหน้าแอปพลิเคชัน GitHub
• scope: ตั้งค่าขอบเขตเป็น "user, repo" ซึ่งตั้งค่าขอบเขตการอนุญาต (นั่นคือ แอปของคุณต้องการเข้าถึงอะไร) สําหรับผู้ใช้
• state: ค่าภายในที่กลไกจัดการ M ส่งผ่าน
• redirect_uri: ตั้งค่าเป็นhttps://oauth.powerbi.com/views/oauthredirect.html

StartLogin = (resourceUrl, state, display) =>
        let
            AuthorizeUrl = "https://github.com/login/oauth/authorize?" & Uri.BuildQueryString([
                client_id = client_id,
                scope = "user, repo",
                state = state,
                redirect_uri = redirect_uri])
        in
            [
                LoginUri = AuthorizeUrl,
                CallbackUri = redirect_uri,
                WindowHeight = windowHeight,
                WindowWidth = windowWidth,
                Context = null
            ];

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

ขั้นตอนที่ 3 - แปลงรหัสที่ได้รับจาก GitHub เป็น access_token

ถ้าผู้ใช้ดําเนินโฟลว์การรับรองความถูกต้องเสร็จสิ้น GitHub จะเปลี่ยนเส้นทางกลับไปยัง URL การเปลี่ยนเส้นทาง Power BI ด้วยรหัสชั่วคราวใน code พารามิเตอร์ เช่นเดียวกับสถานะที่คุณระบุไว้ในขั้นตอนก่อนหน้าใน state พารามิเตอร์ ฟังก์ชันของคุณ FinishLogin จะแยกรหัสออกจาก callbackUri พารามิเตอร์ จากนั้นจึงแลกเปลี่ยนสําหรับโทเค็นการเข้าถึง (โดยใช้ TokenMethod ฟังก์ชัน)

FinishLogin = (context, callbackUri, state) =>
    let
        Parts = Uri.Parts(callbackUri)[Query]
    in
        TokenMethod(Parts[code]);

เพื่อรับโทเค็นการเข้าถึง GitHub คุณส่งรหัสชั่วคราวจากการตอบสนองการอนุญาต GitHub ใน TokenMethod ฟังก์ชัน คุณกําหนดคําขอ POST ไปยังจุดสิ้นสุด access_token ของ GitHub (https://github.com/login/oauth/access_token) พารามิเตอร์ต่อไปนี้จําเป็นสําหรับจุดสิ้นสุด GitHub:

ชื่อ	ชนิด	คำอธิบาย
client_id	string	จำเป็นต้องใช้ ID ไคลเอ็นต์ที่คุณได้รับจาก GitHub เมื่อคุณลงทะเบียน
ข้อมูลลับ_ไคลเอ็นต์	string	จำเป็นต้องใช้ ข้อมูลลับไคลเอ็นต์ที่คุณได้รับจาก GitHub เมื่อคุณลงทะเบียน
รหัส	string	จำเป็นต้องใช้ รหัสที่คุณได้รับในFinishLogin
redirect_uri	string	URL ในแอปของคุณที่จะส่งผู้ใช้หลังจากการรับรองความถูกต้อง ดูรายละเอียดด้านล่างเกี่ยวกับ URL เปลี่ยนเส้นทาง

ต่อไปนี้เป็นรายละเอียดพารามิเตอร์ที่ใช้สําหรับการเรียกใช้ Web.Contents

อาร์กิวเมนต์	คำอธิบาย	ค่า
URL	URL สําหรับเว็บไซต์	https://github.com/login/oauth/access_token
ตัวเลือก	ระเบียนเพื่อควบคุมลักษณะการทํางานของฟังก์ชันนี้	ไม่ได้ใช้ในกรณีนี้
คิวรี	ระบบในการเขียนโปรแกรมเพิ่มพารามิเตอร์คิวรีไปยัง URL	เนื้อหา = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id client_secret = client_secret รหัส = รหัส redirect_uri = redirect_uri ] )) โดย client_id: ID ไคลเอ็นต์จากหน้าแอปพลิเคชัน GitHub client_secret: ข้อมูลลับไคลเอ็นต์จากหน้าแอปพลิเคชัน GitHub code: รหัสในการตอบสนองการให้สิทธิ์ GitHub redirect_uri: URL ในแอปของคุณที่จะส่งผู้ใช้หลังจากการอนุญาต
ส่วนหัว	ระเบียนที่มีส่วนหัวเพิ่มเติมสําหรับคําขอ HTTP	Headers= [ #"Content-type" = "application/x-www-form-urlencoded", #"ยอมรับ" = "application/json" ]

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

TokenMethod = (code) =>
    let
        Response = Web.Contents("https://Github.com/login/oauth/access_token", [
            Content = Text.ToBinary(Uri.BuildQueryString([
                client_id = client_id,
                client_secret = client_secret,
                code = code,
                redirect_uri = redirect_uri])),
            Headers=[#"Content-type" = "application/x-www-form-urlencoded",#"Accept" = "application/json"]]),
        Parts = Json.Document(Response)
    in
        Parts;

การตอบสนอง JSON จากบริการจะประกอบด้วยเขตข้อมูล access_token วิธีการ TokenMethod แปลงการตอบสนอง JSON เป็นระเบียน M โดยใช้ Json.Document และส่งกลับไปยังกลไกจัดการ

การตอบสนองตัวอย่าง:

{
    "access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
    "scope":"user,repo",
    "token_type":"bearer"
}

ขั้นตอนที่ 4 - กําหนดฟังก์ชันที่เข้าถึง GitHub API

ส่วนย่อยของโค้ดต่อไปนี้ส่งออกสองฟังก์ชัน (GithubSample.Contents และ GithubSample.PagedTable) โดยการทําเครื่องหมายเป็น sharedและเชื่อมโยงกับ GithubSample ชนิดแหล่งข้อมูล

[DataSource.Kind="GithubSample", Publish="GithubSample.UI"]
shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.Type) as any);

[DataSource.Kind="GithubSample"]
shared GithubSample.PagedTable = Value.ReplaceType(Github.PagedTable, type function (url as Uri.Type) as nullable table);

ฟังก์ชัน GithubSample.Contents นี้ยังถูกเผยแพร่ไปยัง UI (อนุญาตให้ปรากฏใน กล่องโต้ตอบรับข้อมูล ) ฟังก์ชัน Value.ReplaceType ถูกใช้เพื่อตั้งค่าพารามิเตอร์ฟังก์ชันเป็น Url.Type ชนิดโดยกําหนดไว้

ด้วยการเชื่อมโยงฟังก์ชันเหล่านี้กับ GithubSample ชนิดแหล่งข้อมูล พวกเขาจะใช้ข้อมูลประจําตัวที่ผู้ใช้ให้ไว้โดยอัตโนมัติ ฟังก์ชันไลบรารี M ใด ๆ ที่มีการเปิดใช้งานสําหรับความสามารถในการขยาย (เช่น Web.Contents) จะสืบทอดข้อมูลประจําตัวเหล่านี้โดยอัตโนมัติเช่นกัน

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

URL ตัวอย่าง

ตัวเชื่อมต่อนี้สามารถดึงข้อมูลที่จัดรูปแบบจากจุดสิ้นสุด GitHub v3 REST API ใด ๆ ตัวอย่างเช่น คิวรีที่จะดึงความมุ่งมั่นทั้งหมดไปยังที่เก็บตัวเชื่อมต่อข้อมูลจะมีลักษณะดังนี้:

GithubSample.Contents("https://api.github.com/repos/microsoft/dataconnectors/commits")