Δείγμα σύνδεσης GitHub

Η επέκταση GitHub M δείχνει πώς μπορείτε να προσθέσετε υποστήριξη για μια ροή ελέγχου ταυτότητας πρωτοκόλλου OAuth 2.0. Μπορείτε να μάθετε περισσότερα σχετικά με τις λεπτομέρειες της ροής ελέγχου ταυτότητας του GitHub στην τοποθεσία GitHub Docs.

Πριν ξεκινήσετε τη δημιουργία μιας επέκτασης 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 του Power BI, έτσι ώστε το Power BI να μπορεί να ανακτήσει το access_token και refresh_token.

Πώς να καταχωρήσετε μια εφαρμογή GitHub

Η επέκταση Power BI πρέπει να συνδεθεί στο GitHub. Για να το ενεργοποιήσετε, καταχωρείτε μια νέα εφαρμογή OAuth στο GitHub στη διεύθυνση https://github.com/settings/applications/new.

Application name: Εισαγάγετε ένα όνομα για την εφαρμογή για την επέκταση M.
Authorization callback URL: Εισαγάγετε https://oauth.powerbi.com/views/oauthredirect.html.
Scope: Στο GitHub, ορίστε την εμβέλεια σε user, repo.

Σημείωση

Σε μια καταχωρημένη εφαρμογή OAuth εκχωρείται ένα μοναδικό αναγνωριστικό πελάτη και μυστικός κωδικός πελάτη. Το μυστικό πελάτη δεν πρέπει να κοινοποιείται. Λαμβάνετε το αναγνωριστικό προγράμματος-πελάτη και τον μυστικό κωδικό προγράμματος-πελάτη από τη σελίδα της εφαρμογής GitHub. Ενημερώστε τα αρχεία στο έργο σύνδεσης δεδομένων με το αναγνωριστικό προγράμματος-πελάτη (client_id αρχείο) και το μυστικό προγράμματος-πελάτη (client_secret αρχείο).

Πώς να εφαρμόσετε το GitHub OAuth

Αυτό το δείγμα σας καθοδηγεί στα ακόλουθα βήματα:

Δημιουργήστε έναν ορισμό είδους πηγής δεδομένων που δηλώνει ότι υποστηρίζει OAuth.
Δώστε λεπτομέρειες ώστε ο κινητήρας M να μπορεί να ξεκινήσει τη ροή OAuth (StartLogin).
Μετατρέψτε τον κώδικα που λάβατε από το GitHub σε access_token (FinishLogin και TokenMethod).
Ορίστε συναρτήσεις που έχουν πρόσβαση στο API GitHub (GithubSample.Contents).

Βήμα 1 - Δημιουργήστε έναν ορισμό πηγής δεδομένων

Μια σύνδεση δεδομένων ξεκινά με μια καρτέλα που περιγράφει την επέκταση, συμπεριλαμβανομένου του μοναδικού ονόματός της (που είναι το όνομα της καρτέλας), των υποστηριζόμενων τύπων ελέγχου ταυτότητας και ενός φιλικού εμφανιζόμενου ονόματος (ετικέτα) για την προέλευση δεδομένων. Κατά την υποστήριξη του OAuth, ο ορισμός περιέχει τις συναρτήσεις που υλοποιούν τη σύμβαση OAuth—σε αυτήν την περίπτωση, StartLogin και FinishLogin.

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

Βήμα 2 - Δώστε λεπτομέρειες ώστε ο μηχανισμός M να μπορεί να ξεκινήσει τη ροή OAuth

Η ροή OAuth GitHub ξεκινά όταν κατευθύνετε τους χρήστες στη https://github.com/login/oauth/authorize σελίδα. Για να συνδεθεί ο χρήστης, πρέπει να καθορίσετε έναν αριθμό παραμέτρων ερωτήματος:

Ονομασία	Τύπος	Περιγραφή
client_id	συμβολοσειρά	Υποχρεωτικό. Το αναγνωριστικό προγράμματος-πελάτη που λάβατε από το GitHub κατά την εγγραφή σας.
redirect_uri	συμβολοσειρά	Το URL στην εφαρμογή σας όπου θα κατευθύνονται οι χρήστες μετά την εξουσιοδότηση. Δείτε παρακάτω λεπτομέρειες σχετικά με τα url ανακατεύθυνσης. Για επεκτάσεις M, το `redirect_uri` πρέπει να είναι "https://oauth.powerbi.com/views/oauthredirect.html".
εμβέλεια	συμβολοσειρά	Μια λίστα πεδίων διαχωρισμένη με κόμματα. Εάν δεν παρέχεται, το εύρος ορίζεται από προεπιλογή σε μια κενή λίστα εμβριών για χρήστες που δεν έχουν έγκυρο διακριτικό για την εφαρμογή. Για τους χρήστες που έχουν ήδη ένα έγκυρο διακριτικό για την εφαρμογή, ο χρήστης δεν θα εμφανίζεται στη σελίδα εξουσιοδότησης OAuth με τη λίστα των εμβριών. Αντί για αυτό, αυτό το βήμα της ροής θα ολοκληρωθεί αυτόματα με τα ίδια εύρη που χρησιμοποιήθηκαν την τελευταία φορά που ο χρήστης ολοκλήρωσε τη ροή.
κράτος	συμβολοσειρά	Μια απρόβλεπτη τυχαία συμβολοσειρά. Χρησιμοποιείται για την προστασία από επιθέσεις πλαστογράφησης αιτημάτων μεταξύ τοποθεσιών.

Το παρακάτω απόσπασμα κώδικα περιγράφει τον τρόπο υλοποίησης μιας συνάρτησης StartLogin για την έναρξη της ροής σύνδεσης. Μια StartLogin συνάρτηση παίρνει ένα resourceUrl, state, και display τιμή. Στη συνάρτηση, δημιουργήστε μια AuthorizeUrl που συνενώνει τη διεύθυνση URL εξουσιοδότησης GitHub με τις ακόλουθες παραμέτρους:

client_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	συμβολοσειρά	Υποχρεωτικό. Το αναγνωριστικό προγράμματος-πελάτη που λάβατε από το GitHub κατά την εγγραφή σας.
client_secret	συμβολοσειρά	Υποχρεωτικό. Ο μυστικός κωδικός προγράμματος-πελάτη που λάβατε από το GitHub κατά την εγγραφή σας.
κωδικός	συμβολοσειρά	Υποχρεωτικό. Ο κωδικός που λάβατε στο `FinishLogin`.
redirect_uri	συμβολοσειρά	Το URL στην εφαρμογή σας όπου θα κατευθύνονται οι χρήστες μετά την εξουσιοδότηση. Δείτε παρακάτω λεπτομέρειες σχετικά με τις διευθύνσεις URL ανακατεύθυνσης.

Ακολουθούν οι λεπτομέρειες που χρησιμοποιούνται για την κλήση Web.Contents .

Όρισμα	Περιγραφή	Τιμή
url	Η διεύθυνση URL για την τοποθεσία Web.	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`: Αναγνωριστικό προγράμματος-πελάτη από τη σελίδα εφαρμογής GitHub. `client_secret`: Μυστικός κωδικός προγράμματος-πελάτη από τη σελίδα εφαρμογής GitHub. `code`: Κώδικας στην απόκριση εξουσιοδότησης GitHub. `redirect_uri`: Το URL στην εφαρμογή σας όπου θα κατευθύνονται οι χρήστες μετά την εξουσιοδότηση.
Κεφαλίδες	Μια εγγραφή με πρόσθετες κεφαλίδες για την αίτηση HTTP.	`Κεφαλίδες= [ #"Content-type" = "application/x-www-form-urlencoded", #"Αποδοχή" = "εφαρμογή/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 συνάρτηση δημοσιεύεται επίσης στο περιβάλλον εργασίας χρήστη (επιτρέποντάς της να εμφανίζεται στο παράθυρο διαλόγου Λήψη δεδομένων ). Η συνάρτηση Value.ReplaceType χρησιμοποιείται για τον ορισμό της παραμέτρου συνάρτησης στον Url.Type τύπο που αποδίδεται.

Συσχετίζοντας αυτές τις συναρτήσεις με το GithubSample είδος προέλευσης δεδομένων, θα χρησιμοποιήσουν αυτόματα τα διαπιστευτήρια που παρείχε ο χρήστης. Όλες οι λειτουργίες της βιβλιοθήκης M που έχουν ενεργοποιηθεί για επεκτασιμότητα (όπως το Web.Contents) θα κληρονομήσουν αυτόματα και αυτά τα διαπιστευτήρια.

Για περισσότερες λεπτομέρειες σχετικά με τον τρόπο λειτουργίας των διαπιστευτηρίων και του ελέγχου ταυτότητας, ανατρέξτε στην ενότητα Χειρισμός ελέγχου ταυτότητας.

Δείγμα διεύθυνσης URL

Αυτή η σύνδεση είναι σε θέση να ανακτήσει μορφοποιημένα δεδομένα από οποιοδήποτε από τα τελικά σημεία του GitHub v3 REST API. Για παράδειγμα, το ερώτημα για τη λήψη όλων των υποβολών στο αποθετήριο συνδέσεων δεδομένων θα έχει την εξής μορφή:

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

Ανάδραση

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2023-03-23