Partilhar via

Exemplo do GitHub Connector

A extensão GitHub M mostra como adicionar suporte para um fluxo de autenticação do protocolo OAuth 2.0. Pode saber mais sobre os detalhes do fluxo de autenticação do GitHub no site GitHub Docs.

Antes de começares a criar uma extensão M, precisas de registar uma nova aplicação no GitHub e substituir os client_id ficheiros e client_secret pelos valores apropriados para a tua aplicação.

Nota sobre problemas de compatibilidade no Visual Studio:O Power Query SDK utiliza um controlo baseado no Internet Explorer para abrir diálogos OAuth. O GitHub deixou de suportar a versão do IE usada por este controlo, o que o impedirá de completar a concessão de permissão para a sua aplicação se for executada dentro do Visual Studio. Uma alternativa é carregar a extensão com o Power BI Desktop e completar o primeiro fluxo OAuth aí. Depois de a sua aplicação ter acesso à sua conta, os logins subsequentes funcionarão bem a partir do Visual Studio.

OAuth e Power BI

OAuth é uma forma de delegação de credenciais. Ao iniciar sessão no GitHub e autorizar a "aplicação" que cria para o GitHub, o utilizador permite que a sua "aplicação" faça login em seu nome para recuperar dados no Power BI. A "aplicação" deve receber direitos para recuperar dados (obter um access_token) e para atualizar os dados num calendário (obter e usar um refresh_token). A sua "aplicação" neste contexto é o seu Conector de Dados usado para executar consultas dentro do Power BI. O Power BI armazena e gere a access_token e refresh_token em seu nome.

Observação

Para permitir que o Power BI obtenha e use a access_token, deve especificar a URL de redirecionamento como https://oauth.powerbi.com/views/oauthredirect.html.

Quando especificas este URL e o GitHub autentica e concede permissões com sucesso, o GitHub redireciona para o endpoint oauthredirect do Power BI para que o Power BI possa recuperar o access_token e o refresh_token.

Como registar uma aplicação no GitHub

A sua extensão Power BI precisa de iniciar sessão no GitHub. Para ativar isto, regista uma nova aplicação OAuth no GitHub em https://github.com/settings/applications/new.

  1. Application name: Introduza um nome para a aplicação da sua extensão M.
  2. Authorization callback URL: Insira https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: No GitHub, defina o âmbito para user, repo.

Observação

Uma aplicação OAuth registada recebe um ID de Cliente único e um Segredo do Cliente. O Segredo do Cliente não deve ser partilhado. Obtém o ID do Cliente e o Segredo do Cliente na página da aplicação do GitHub. Atualize os ficheiros no seu projeto Data Connector com o ID do Cliente (client_id ficheiro) e o Segredo do Cliente (client_secret ficheiro).

Como implementar o GitHub OAuth

Este exemplo guia-o pelos seguintes passos:

  1. Crie uma definição de Tipo de Fonte de Dados que declare que suporta OAuth.
  2. Forneça detalhes para que o motor M possa iniciar o fluxo OAuth (StartLogin).
  3. Converta o código recebido do GitHub numa access_token (FinishLogin e TokenMethod).
  4. Defina funções que acedam à API do GitHub (GithubSample.Contents).

Passo 1 - Criar uma definição de Fonte de Dados

Um Conector de Dados começa com um registo que descreve a extensão, incluindo o seu nome único (que é o nome do registo), os tipos de autenticação suportados e um nome de visualização amigável (rótulo) para a fonte de dados. Ao suportar o OAuth, a definição contém as funções que implementam o contrato OAuth — neste caso, StartLogin e FinishLogin.

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

Passo 2 - Forneça detalhes para que o motor M possa iniciar o fluxo OAuth

O fluxo OAuth do GitHub começa quando direcionas os utilizadores para a https://github.com/login/oauth/authorize página. Para o utilizador iniciar sessão, precisa de especificar vários parâmetros de consulta:

Nome Tipo Description
ID do cliente cadeia (de caracteres) Obrigatório. O ID do cliente que recebeu do GitHub quando se registou.
redirect_uri cadeia (de caracteres) A URL na sua aplicação para onde os utilizadores serão enviados após a autorização. Veja os detalhes seguintes sobre URLs de redirecionamento. Para M extensões, o redirect_uri deve ser "https://oauth.powerbi.com/views/oauthredirect.html".
âmbito cadeia (de caracteres) Uma vírgula separava uma lista de miras. Se não for fornecido, o âmbito será, por defeito, uma lista vazia de âmbitos para utilizadores que não têm um token válido para a aplicação. Para utilizadores que já têm um token válido para a aplicação, não será mostrada a página de autorização OAuth com a lista de escopos. Em vez disso, esta etapa do fluxo será automaticamente concluída com os mesmos parâmetros usados na última vez que o utilizador completou o fluxo.
state cadeia (de caracteres) Uma sequência aleatória impossível de adivinhar. É usado para proteger contra ataques de falsificação de requisições entre sites.

O seguinte excerto de código descreve como implementar uma StartLogin função para iniciar o fluxo de login. Uma StartLogin função tem um resourceUrl, state, e display um valor. Na função, crie um AuthorizeUrl que concatene o URL de autorização do GitHub com os seguintes parâmetros:

  • client_id: Recebe o ID do cliente depois de registar a sua extensão no GitHub a partir da página da aplicação do GitHub.
  • scope: Defina o âmbito para "user, repo". Isto define o âmbito de autorização (ou seja, o que a sua aplicação quer aceder) para o utilizador.
  • state: Um valor interno que o motor M transmite.
  • redirect_uri: Defina como 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 for a primeira vez que o utilizador inicia sessão com a sua aplicação (identificada pelo seu client_id valor), verá uma página que lhe pede para conceder acesso à sua aplicação. As tentativas subsequentes de login vão pedir as suas credenciais.

Passo 3 - Converter o código recebido do GitHub numa access_token

Se o utilizador completar o fluxo de autenticação, o GitHub redireciona de volta para a URL de redirecionamento do Power BI com um código temporário num code parâmetro, bem como para o estado que forneceu na etapa anterior num state parâmetro. A tua FinishLogin função irá extrair o código do callbackUri parâmetro e depois trocá-lo por um token de acesso (usando a TokenMethod função).

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

Para obter um token de acesso ao GitHub, passa-se o código temporário da Resposta de Autorização do GitHub. Na TokenMethod função, formula-se um pedido POST para o endpoint access_token do GitHub (https://github.com/login/oauth/access_token). Os seguintes parâmetros são necessários para o endpoint do GitHub:

Nome Tipo Description
ID do cliente cadeia (de caracteres) Obrigatório. O ID do cliente que recebeu do GitHub quando se registou.
client_secret cadeia (de caracteres) Obrigatório. O segredo do cliente que recebeu do GitHub quando se registou.
código cadeia (de caracteres) Obrigatório. O código que recebeu em FinishLogin.
redirect_uri cadeia (de caracteres) A URL na sua aplicação para onde os utilizadores serão enviados após a autorização. Veja os detalhes seguintes sobre URLs de redirecionamento.

Aqui estão os detalhes dos parâmetros usados para a chamada Web.Contents .

Argument Description Valor
URL O URL do site. https://github.com/login/oauth/access_token
options Um registo para controlar o comportamento desta função. Não utilizado neste caso
Query Adicione programaticamente parâmetros de consulta à URL. Content = Texto.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
código = código,
redirect_uri = redirect_uri
]
))
Onde
  • client_id: ID do cliente da página da aplicação GitHub.
  • client_secret: Segredo do cliente da página da aplicação GitHub.
  • code: Código na resposta de autorização do GitHub.
  • redirect_uri: O URL na sua aplicação para onde os utilizadores serão enviados após a autorização.
Headers Um registo com cabeçalhos adicionais para o pedido HTTP. Cabeçalhos= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

Este excerto de código descreve como implementar uma TokenMethod função para trocar um código de autenticação por um token de acesso.

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;

A resposta JSON do serviço conterá um campo access_token. O TokenMethod método converte a resposta JSON num registo M usando Json.Document e devolve-a ao motor.

Exemplo de resposta:

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

Passo 4 - Definir funções que acedam à API do GitHub

O seguinte excerto de código exporta duas funções (GithubSample.Contents e GithubSample.PagedTable) marcando-as como shared, e associa-as ao GithubSample Tipo de Fonte de Dados.

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

A GithubSample.Contents função também é publicada na interface (permitindo que apareça no diálogo Obter Dados ). A função Value.ReplaceType é usada para definir o parâmetro da função ao Url.Type tipo atribuído.

Ao associar estas funções ao GithubSample tipo de fonte de dados, eles usam automaticamente as credenciais que o utilizador forneceu. Quaisquer funções da biblioteca M que tenham sido ativadas para extensibilidade (como Web.Contents) herdarão automaticamente estas credenciais também.

Para mais detalhes sobre como funcionam credenciais e autenticação, veja Gestão da Autenticação.

URL de exemplo

Este conector é capaz de recuperar dados formatados de qualquer um dos endpoints da API REST do GitHub v3. Por exemplo, a consulta para puxar todos os commits para o repositório Data Connectors seria a seguinte:

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