Condividi tramite

Esempio di connettore GitHub

  • Articolo

L'estensione GitHub M illustra come aggiungere il supporto per un flusso di autenticazione del protocollo OAuth 2.0. Per altre informazioni sulle specifiche del flusso di autenticazione di GitHub, vedere il sito per sviluppatori GitHub.

Prima di iniziare a creare un'estensione M, è necessario registrare una nuova app in GitHub e sostituire i client_id file e client_secret con i valori appropriati per l'app.

Nota sui problemi di compatibilità in Visual Studio: Power Query SDK usa un controllo basato su Internet Explorer per visualizzare finestre di dialogo OAuth popup. GitHub ha deprecato il supporto per la versione di Internet Explorer usata da questo controllo, che impedirà di completare la concessione di autorizzazioni per l'app se eseguita da Visual Studio. Un'alternativa consiste nel caricare l'estensione con Power BI Desktop e completare il primo flusso OAuth. Dopo che l'applicazione ha concesso l'accesso all'account, gli account di accesso successivi funzioneranno correttamente da Visual Studio.

OAuth e Power BI

OAuth è una forma di delega delle credenziali. Accedendo a GitHub e autorizzando l'"applicazione" creata per GitHub, l'utente consente all'"applicazione" di accedere per suo conto per recuperare i dati in Power BI. All'applicazione devono essere concessi diritti per recuperare i dati (ottenere un access_token) e aggiornare i dati in base a una pianificazione (ottenere e usare un refresh_token). L'"applicazione" in questo contesto è il connettore dati usato per eseguire query all'interno di Power BI. Power BI archivia e gestisce le access_token e le refresh_token per conto dell'utente.

Nota

Per consentire a Power BI di ottenere e usare il access_token, è necessario specificare l'URL di reindirizzamento come https://oauth.powerbi.com/views/oauthredirect.html.

Quando si specifica questo URL e GitHub esegue correttamente l'autenticazione e concede le autorizzazioni, GitHub reindirizza all'endpoint oauthredirect di Power BI in modo che Power BI possa recuperare il access_token e refresh_token.

Come registrare un'app GitHub

L'estensione di Power BI deve accedere a GitHub. Per abilitare questa operazione, registrare una nuova applicazione OAuth con GitHub all'indirizzo https://github.com/settings/applications/new.

  1. Application name: immettere un nome per l'applicazione per l'estensione M.
  2. Authorization callback URL: immettere https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: in GitHub impostare l'ambito su user, repo.

Nota

A un'applicazione OAuth registrata viene assegnato un ID client univoco e un segreto client. Il segreto client non deve essere condiviso. L'ID client e il segreto client vengono visualizzati nella pagina dell'applicazione GitHub. Aggiornare i file nel progetto data connector con l'ID client (client_id file) e il segreto client (client_secret file).

Come implementare GitHub OAuth

Questo esempio illustra i passaggi seguenti:

  1. Creare una definizione del tipo di origine dati che lo dichiara supporta.
  2. Specificare i dettagli in modo che il motore M possa avviare il flusso OAuth (StartLogin).
  3. Convertire il codice ricevuto da GitHub in un access_token (FinishLogin e TokenMethod).
  4. Definire le funzioni che accedono all'API GitHub (GithubSample.Contents).

Passaggio 1: Creare una definizione di origine dati

Un connettore dati inizia con un record che descrive l'estensione, incluso il nome univoco (ovvero il nome del record), i tipi di autenticazione supportati e un nome visualizzato descrittivo (etichetta) per l'origine dati. Quando si supporta OAuth, la definizione contiene le funzioni che implementano il contratto OAuth, StartLogin in questo caso e FinishLogin.

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

Passaggio 2- Specificare i dettagli in modo che il motore M possa avviare il flusso OAuth

Il flusso OAuth di GitHub inizia quando si indirizzano gli utenti alla https://github.com/login/oauth/authorize pagina. Per consentire all'utente di accedere, è necessario specificare un numero di parametri di query:

Nome Tipo Descrizione
client_id string Obbligatorio. ID client ricevuto da GitHub al momento della registrazione.
redirect_uri string URL nell'app in cui gli utenti verranno inviati dopo l'autorizzazione. Vedere i dettagli seguenti sugli URL di reindirizzamento. Per le estensioni M, deve redirect_uri essere "https://oauth.powerbi.com/views/oauthredirect.html".
ambito string Elenco delimitato da virgole di ambiti. Se non specificato, per impostazione predefinita l'ambito è un elenco vuoto di ambiti per gli utenti che non dispongono di un token valido per l'app. Per gli utenti che hanno già un token valido per l'app, l'utente non visualizzerà la pagina di autorizzazione OAuth con l'elenco di ambiti. Al contrario, questo passaggio del flusso verrà completato automaticamente con gli stessi ambiti usati l'ultima volta che l'utente ha completato il flusso.
state string Stringa casuale indovinabile. Viene usato per proteggersi da attacchi falsi di richiesta intersito.

Il frammento di codice seguente descrive come implementare una StartLogin funzione per avviare il flusso di accesso. Una StartLogin funzione accetta un resourceUrlvalore , statee display . Nella funzione creare un oggetto AuthorizeUrl che concatena l'URL di autorizzazione di GitHub con i parametri seguenti:

  • client_id: si ottiene l'ID client dopo aver registrato l'estensione con GitHub dalla pagina dell'applicazione GitHub.
  • scope: impostare l'ambito su "user, repo". In questo modo viene impostato l'ambito di autorizzazione, ovvero ciò che l'app vuole accedere, per l'utente.
  • state: valore interno passato dal motore M.
  • redirect_uri: impostare su 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
            ];

Se questa è la prima volta che l'utente accede con la tua app (identificata dal valore), client_id visualizzerà una pagina che chiede loro di concedere l'accesso all'app. I tentativi di accesso successivi richiederanno semplicemente le credenziali.

Passaggio 3: Convertire il codice ricevuto da GitHub in un access_token

Se l'utente completa il flusso di autenticazione, GitHub reindirizza nuovamente all'URL di reindirizzamento di Power BI con un codice temporaneo in un code parametro, nonché lo stato specificato nel passaggio precedente in un state parametro. La FinishLogin funzione estrae il codice dal callbackUri parametro e quindi lo scambia per un token di accesso (usando la TokenMethod funzione ).

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

Per ottenere un token di accesso GitHub, passare il codice temporaneo dalla risposta di autorizzazione di GitHub. TokenMethod Nella funzione si formula una richiesta POST all'endpoint access_token di GitHub (https://github.com/login/oauth/access_token). Per l'endpoint GitHub sono necessari i parametri seguenti:

Nome Tipo Descrizione
client_id string Obbligatorio. ID client ricevuto da GitHub al momento della registrazione.
client_secret string Obbligatorio. Segreto client ricevuto da GitHub al momento della registrazione.
codice string Obbligatorio. Codice ricevuto in FinishLogin.
redirect_uri string URL nell'app in cui gli utenti verranno inviati dopo l'autorizzazione. Vedere i dettagli seguenti sugli URL di reindirizzamento.

Ecco i dettagli usati parametri per la chiamata Web.Contents .

Argomento Descrizione Valore
URL. URL del sito Web. https://github.com/login/oauth/access_token
opzioni Record per controllare il comportamento di questa funzione. Non usato in questo caso
Query Aggiungere parametri di query all'URL a livello di codice. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Dove
  • client_id: ID client dalla pagina dell'applicazione GitHub.
  • client_secret: segreto client dalla pagina dell'applicazione GitHub.
  • code: codice nella risposta di autorizzazione di GitHub.
  • redirect_uri: URL nell'app in cui gli utenti verranno inviati dopo l'autorizzazione.
Intestazioni Record con intestazioni aggiuntive per la richiesta HTTP. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

Questo frammento di codice descrive come implementare una TokenMethod funzione per scambiare un codice di autenticazione per un token di accesso.

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;

La risposta JSON dal servizio conterrà un campo access_token. Il TokenMethod metodo converte la risposta JSON in un record M usando Json.Document e la restituisce al motore.

Risposta campione:

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

Passaggio 4: Definire le funzioni che accedono all'API GitHub

Il frammento di codice seguente esporta due funzioni (GithubSample.Contents e GithubSample.PagedTable) contrassegnandole come sharede le associa al GithubSample tipo di origine dati.

[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);

La GithubSample.Contents funzione viene pubblicata anche nell'interfaccia utente (consentendo la visualizzazione nella finestra di dialogo Recupera dati ). La funzione Value.ReplaceType viene utilizzata per impostare il parametro della funzione sul Url.Type tipo ascritto.

Associando queste funzioni al GithubSample tipo di origine dati, useranno automaticamente le credenziali fornite dall'utente. Tutte le funzioni della libreria M abilitate per l'estendibilità (ad esempio Web.Contents) erediteranno automaticamente anche queste credenziali.

Per altre informazioni sul funzionamento delle credenziali e dell'autenticazione, vedere Gestione dell'autenticazione.

URL di esempio

Questo connettore è in grado di recuperare i dati formattati da qualsiasi endpoint dell'API REST di GitHub v3. Ad esempio, la query per eseguire il pull di tutti i commit nel repository Data Connectors sarà simile alla seguente:

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