Κοινή χρήση μέσω

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

  • Άρθρο

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

Πριν ξεκινήσετε τη δημιουργία μιας επέκτασης M, πρέπει να καταχωρήσετε μια νέα εφαρμογή στο GitHub και να αντικαταστήσετε τα client_id αρχεία και client_secret με τις κατάλληλες τιμές για την εφαρμογή σας.

Σημείωση σχετικά με ζητήματα συμβατότητας στο Visual Studio: Το SDK Power Query χρησιμοποιεί ένα στοιχείο ελέγχου που βασίζεται στον 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 εκχωρείται ένα μοναδικό αναγνωριστικό προγράμματος-πελάτη και ένας μυστικός κωδικός προγράμματος-πελάτη. Ο μυστικός κωδικός προγράμματος-πελάτη δεν πρέπει να είναι κοινόχρηστος. Λαμβάνετε το Αναγνωριστικό προγράμματος-πελάτη και τον Μυστικό κωδικό προγράμματος-πελάτη από τη σελίδα της εφαρμογής GitHub. Ενημερώστε τα αρχεία στο έργο Data Connector με το Αναγνωριστικό προγράμματος-πελάτη (client_id αρχείο) και τον Μυστικό κωδικό προγράμματος-πελάτη (client_secret αρχείο).

Πώς να υλοποιήσετε το GitHub OAuth

Αυτό το δείγμα θα σας καθοδηγεί στα παρακάτω βήματα:

  1. Δημιουργήστε έναν ορισμό είδος προέλευσης δεδομένων που δηλώνει ότι υποστηρίζει OAuth.
  2. Καταχωρήστε λεπτομέρειες ώστε ο μηχανισμός M να μπορεί να εκκινήσει τη ροή OAuth (StartLogin).
  3. Μετατρέψτε τον κώδικα που λάβατε από το GitHub σε access_token (FinishLogin και TokenMethod).
  4. Καθορίστε συναρτήσεις που έχουν πρόσβαση στο 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

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

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

Το παρακάτω τμήμα κώδικα περιγράφει τον τρόπο υλοποίησης μιας 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:

Ονομασία Τύπος Description
client_id συμβολοσειρά Απαιτείται. Το αναγνωριστικό προγράμματος-πελάτη που λάβατε από το GitHub κατά την εγγραφή σας.
client_secret συμβολοσειρά Απαιτείται. Ο μυστικός κωδικός προγράμματος-πελάτη που λάβατε από το GitHub κατά την εγγραφή σας.
κωδικός συμβολοσειρά Απαιτείται. Ο κωδικός που λάβατε στο FinishLogin.
redirect_uri συμβολοσειρά Η διεύθυνση URL στην εφαρμογή σας όπου οι χρήστες θα σταλούν μετά την εξουσιοδότηση. Δείτε λεπτομέρειες παρακάτω σχετικά με τις διευθύνσεις URL ανακατεύθυνσης.

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

Όρισμα Περιγραφή Τιμή
url Η διεύθυνση URL για την τοποθεσία Web. https://github.com/login/oauth/access_token
επιλογές Μια εγγραφή για τον έλεγχο της συμπεριφοράς αυτής της συνάρτησης. Δεν χρησιμοποιείται σε αυτή την περίπτωση
Query Προσθέστε μέσω προγραμματισμού παραμέτρους ερωτημάτων στη διεύθυνση URL. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Όπου
  • client_id: Αναγνωριστικό προγράμματος-πελάτη από τη σελίδα εφαρμογής GitHub.
  • client_secret: Μυστικός κωδικός προγράμματος-πελάτη από τη σελίδα εφαρμογής GitHub.
  • code: Κωδικός στην απόκριση εξουσιοδότησης GitHub.
  • redirect_uri: Η διεύθυνση URL στην εφαρμογή σας όπου θα αποστέλλονται οι χρήστες μετά την εξουσιοδότηση.
Κεφαλίδες Μια εγγραφή με πρόσθετες κεφαλίδες για την αίτηση HTTP. Κεφαλίδες= [
#"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 - Καθορίστε συναρτήσεις που έχουν πρόσβαση στο API του GitHub

Το ακόλουθο τμήμα κώδικα εξάγει δύο συναρτήσεις (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

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

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