Compartilhar via

Exemplo do Conector do GitHub

A extensão do GitHub M mostra como adicionar suporte a um fluxo de autenticação de protocolo OAuth 2.0. Você pode saber mais sobre as especificidades do fluxo de autenticação do GitHub no site do GitHub Docs.

Antes de começar a criar uma extensão M, você precisa registrar um novo aplicativo no GitHub e substituir os arquivos client_id e client_secret pelos valores apropriados para seu aplicativo.

Observação sobre problemas de compatibilidade no Visual Studio:o SDK do Power Query usa um controle baseado no Internet Explorer para pop-up de caixas de diálogo OAuth. O GitHub preteriu seu suporte para a versão do IE usada por esse controle, o que impedirá que você concatena a concessão de permissão para seu aplicativo se for executado no Visual Studio. Uma alternativa é carregar a extensão com o Power BI Desktop e concluir o primeiro fluxo OAuth lá. Depois que o aplicativo tiver recebido acesso à sua conta, os logons subsequentes funcionarão bem no Visual Studio.

OAuth e Power BI

O OAuth é uma forma de delegação de credenciais. Ao fazer logon no GitHub e autorizar o "aplicativo" criado para o GitHub, o usuário está permitindo que seu "aplicativo" faça logon em seu nome para recuperar dados no Power BI. O "aplicativo" deve receber direitos para recuperar dados (obter um access_token) e atualizar os dados em um agendamento (obter e usar um refresh_token). Seu "aplicativo" nesse contexto é o Conector de Dados usado para executar consultas no Power BI. O Power BI armazena e gerencia o access_token e refresh_token em seu nome.

Observação

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

Quando você especificar essa URL e o GitHub autenticar e conceder permissões com êxito, o GitHub redirecionará para o ponto de extremidade oauthredirect do Power BI para que o Power BI possa recuperar o access_token e refresh_token.

Como registrar um aplicativo do GitHub

Sua extensão do Power BI precisa fazer logon no GitHub. Para habilitar isso, registre um novo aplicativo OAuth com o GitHub em https://github.com/settings/applications/new.

  1. Application name: Digite um nome para o aplicativo da sua extensão M.
  2. Authorization callback URL: introduza https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: no GitHub, defina o escopo como user, repo.

Observação

Um aplicativo OAuth registrado recebe uma ID de cliente exclusiva e um segredo do cliente. O Segredo do Cliente não deve ser compartilhado. Você obtém a ID do cliente e o segredo do cliente na página do aplicativo GitHub. Atualize os arquivos em seu projeto do Conector de Dados com a Identificação do Cliente (client_id arquivo) e a Chave Secreta do Cliente (client_secret arquivo).

Como implementar o GitHub OAuth

Este exemplo orienta você pelas seguintes etapas:

  1. Crie uma definição de Tipo de Fonte de Dados que declare que dá suporte ao OAuth.
  2. Forneça detalhes para que o mecanismo M possa iniciar o fluxo OAuth (StartLogin).
  3. Converter o código recebido do GitHub em um access_token (FinishLogin e TokenMethod).
  4. Defina funções que acessam a API do GitHub (GithubSample.Contents).

Etapa 1 – Criar uma definição de Fonte de Dados

Um Conector de Dados começa com um registro que descreve a extensão, incluindo seu nome exclusivo (que é o nome do registro), tipos de autenticação com suporte e um nome de exibição amigável (rótulo) para a fonte de dados. Ao dar suporte ao OAuth, a definição contém as funções que implementam o contrato OAuth, nesse caso, StartLogin e FinishLogin.

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

Etapa 2 – Fornecer detalhes para que o mecanismo M possa iniciar o fluxo OAuth

O fluxo OAuth do GitHub é iniciado quando você direciona os usuários para a https://github.com/login/oauth/authorize página. Para que o usuário faça logon, você precisa especificar uma série de parâmetros de consulta:

Nome Tipo Description
ID do cliente cadeia Obrigatório. A ID do cliente que você recebeu do GitHub quando se registrou.
URI de redirecionamento cadeia A URL em seu aplicativo para onde os usuários serão enviados após a autorização. Veja os detalhes a seguir sobre urls de redirecionamento. Para extensões M, deve redirect_uri ser "https://oauth.powerbi.com/views/oauthredirect.html".
escopo cadeia Uma lista de escopos separada por vírgulas. Se não for fornecido, o escopo usará como padrão uma lista vazia de escopos para usuários que não têm um token válido para o aplicativo. Para usuários que já têm um token válido para o aplicativo, o usuário não será mostrado na página de autorização do OAuth com a lista de escopos. Em vez disso, essa etapa do fluxo será concluída automaticamente com os mesmos escopos que foram usados na última vez que o usuário concluiu o fluxo.
estado cadeia Uma string aleatória indescritível. É usado para proteger contra ataques de falsificação de solicitações entre sites.

O snippet de código a seguir descreve como implementar uma StartLogin função para iniciar o fluxo de logon. Uma StartLogin função aceita um resourceUrl, um state e um valor display. Na função, crie um AuthorizeUrl que concatena a URL de autorização do GitHub com os seguintes parâmetros:

  • client_id: você obtém a ID do cliente depois de registrar sua extensão no GitHub na página do aplicativo GitHub.
  • scope: defina o escopo como "user, repo". Isso define o escopo de autorização (ou seja, o que seu aplicativo deseja acessar) para o usuário.
  • state: um valor interno que é repassado pelo mecanismo M.
  • redirect_uri: definido 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 esta for a primeira vez que o usuário estiver fazendo login com o seu aplicativo (identificado pelo valor client_id), ele verá uma página solicitando que conceda acesso ao seu aplicativo. As tentativas de logon subsequentes solicitarão suas credenciais.

Etapa 3 – Converter o código recebido do GitHub em um access_token

Se o usuário concluir o fluxo de autenticação, o GitHub redirecionará de volta para a URL de redirecionamento do Power BI com um código temporário em um code parâmetro, bem como o estado fornecido na etapa anterior em um state parâmetro. Sua FinishLogin função extrairá o código do callbackUri parâmetro e o trocará 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 do GitHub, você passa o código temporário da Resposta de Autorização do GitHub. Na função TokenMethod, você formula uma solicitação 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 Obrigatório. A ID do cliente que você recebeu do GitHub quando se registrou.
segredo_do_cliente cadeia Obrigatório. O segredo do cliente que você recebeu do GitHub quando se registrou.
codificar cadeia Obrigatório. O código que você recebeu em FinishLogin.
URI de redirecionamento cadeia A URL em seu aplicativo para onde os usuários serão enviados após a autorização. Veja os detalhes a seguir sobre URLs de redirecionamento.

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

Argument Description Value
url A URL do site da Web. https://github.com/login/oauth/access_token
Opções Um registro para controlar o comportamento dessa função. Não usado nesse caso
Query Adicione programaticamente parâmetros de consulta à URL. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = código
redirect_uri = redirect_uri
]
))
Where
  • client_id: ID do cliente da página do aplicativo GitHub.
  • client_secret: segredo do cliente na página do aplicativo GitHub.
  • code: código na resposta de autorização do GitHub.
  • redirect_uri: a URL em seu aplicativo para onde os usuários serão enviados após a autorização.
Headers Um registro com cabeçalhos adicionais para a solicitação HTTP. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
# "Accept" = "application/json"
]

Este snippet 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 em um registro M usando Json.Document e a retorna para o mecanismo.

Resposta de exemplo:

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

Etapa 4 – Definir funções que acessam a API do GitHub

O snippet de código a seguir exporta duas funções (GithubSample.Contents e GithubSample.PagedTable) marcando-as como sharede as associa ao Tipo de GithubSample 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 do usuário (permitindo que ela apareça na caixa de diálogo Obter Dados ). A função Value.ReplaceType é usada para definir o parâmetro de função para o Url.Type tipo inscrito.

Ao associar essas funções ao tipo de GithubSample fonte de dados, elas usarão automaticamente as credenciais fornecidas pelo usuário. Todas as funções da biblioteca M habilitadas para extensibilidade (como Web.Contents) herdarão automaticamente essas credenciais também.

Para obter mais detalhes sobre como funciona a credencial e a autenticação, consulte Manipulando a Autenticação.

URL de exemplo

Esse conector recupera dados formatados de qualquer endpoint da API REST do GitHub v3. Por exemplo, a consulta para buscar todos os commits do repositório de Conectores de Dados teria a seguinte aparência:

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