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. Saiba mais sobre as especificidades do fluxo de autenticação do GitHub no site do Desenvolvedor do GitHub.

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 abrir 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ê conclua 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 do OAuth lá. Depois que o aplicativo tiver recebido acesso à sua conta, os logons subsequentes funcionarão bem no Visual Studio.

OAuth e Power BI

OAuth é uma forma de delegação de credenciais. Ao fazer logon no GitHub e autorizar o "aplicativo" criado para o GitHub, o usuário permite 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 o refresh_token em seu nome.

Observação

Para permitir que o Power BI obtenha e use o access_token, você deve especificar 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 sucesso, o GitHub redirecionará para o ponto de extremidade oauthredirect do PowerBI para que o Power BI possa recuperar o access_token e o refresh_token.

Como registrar um aplicativo 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: insira um nome para o aplicativo para sua extensão M.
2. Authorization callback URL: insira 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 do Cliente e um Segredo do Cliente exclusivos. 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 ID do Cliente (arquivo client_id) e o Segredo do Cliente (arquivo client_secret).

Como implementar o GitHub OAuth

O exemplo guiará você pelas etapas a seguir:

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 do OAuth (StartLogin).
3. Converta 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 do 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 do OAuth

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

Nome	Tipo	Descrição
client_id	string	Obrigatório. A ID do cliente que você recebeu do GitHub quando se registrou.
redirect_uri	string	A URL no seu aplicativo para o qual os usuários serão enviados depois da autorização. Veja detalhes abaixo sobre as URLs de redirecionamento. Para extensões M, redirect_uri deve ser "https://oauth.powerbi.com/views/oauthredirect.html".
scope	string	Lista de escopos separados por vírgulas Se não for fornecido, o escopo será padrão para 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, a página de autorização OAuth com a lista de escopos não será exibida para o usuário. Em vez disso, essa etapa do fluxo será concluída automaticamente com os mesmos escopos que foram usados na última vez em que o usuário concluiu o fluxo.
estado	string	Uma string aleatória indescritível. É usada para proteger contra ataques de solicitação intersite forjada.

O snippet de código a seguir descreve como implementar uma função StartLogin para iniciar o fluxo de logon. Uma função StartLogin usa um valor resourceUrl, state e 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 do GitHub.
• scope: defina o escopo como "user, repo". Isso define o escopo da autorização (ou seja, o que seu aplicativo deseja acessar) para o usuário.
• state: um valor interno que o mecanismo M passa.
• 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 essa for a primeira vez que o usuário estiver fazendo logon com seu aplicativo (identificado por seu valor client_id), ele verá uma página que solicita que ele conceda acesso ao seu aplicativo. As tentativas de logon subsequentes somente solicitarão suas credenciais.

Etapa 3: converta o código recebido do GitHub em um access_token

Se o usuário concluir o fluxo de autenticação, o GitHub o redirecionará de volta para a URL de redirecionamento do Power BI com um código temporário em um parâmetro code, bem como o estado que você forneceu na etapa anterior em um parâmetro state. Sua função FinishLogin extrairá o código do parâmetro callbackUri e o trocará por um token de acesso (usando a função TokenMethod).

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

Para obter um token de acesso do GitHub, passe o código temporário da resposta de autorização do GitHub. Na função TokenMethod, você formula uma solicitação POST para o ponto de extremidade de access_token do GitHub (https://github.com/login/oauth/access_token). Os seguintes parâmetros são necessários para o ponto de extremidade do GitHub:

Nome	Tipo	Descrição
client_id	string	Obrigatório. A ID do cliente que você recebeu do GitHub quando se registrou.
client_secret	string	Obrigatório. O segredo do cliente que você recebeu do GitHub quando se registrou.
código	string	Obrigatório. O código que você recebeu em FinishLogin.
redirect_uri	string	A URL no seu aplicativo para o qual os usuários serão enviados depois da autorização. Veja detalhes abaixo sobre as URLs de redirecionamento.

Aqui estão os detalhes usados para a chamada Web.Contents.

Argument	Descrição	Valor
url	A URL para o site.	https://github.com/login/oauth/access_token
opções	Um registro para controlar o comportamento dessa função.	Não usado nesse caso
Consulta	Adicionar programaticamente parâmetros de consulta à URL.	Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] )) Onde client_id: ID do cliente da página do aplicativo GitHub. client_secret: segredo do cliente da página do aplicativo GitHub. code: código na resposta de autorização do GitHub. redirect_uri: a URL no seu aplicativo para o qual os usuários serão enviados depois da autorização.
Cabeçalhos	Um registro com mais cabeçalhos para a solicitação HTTP.	Cabeçalhos= [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]

Este snippet de código descreve como implementar uma função TokenMethod 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 terá um campo access_token. O método TokenMethod converte a resposta JSON em um registro M usando Json.Document e a retorna ao mecanismo.

Exemplo de resposta:

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

Etapa 4: defina 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 Fonte de Dados 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);

A função GithubSample.Contents 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 tipo Url.Type atribuído.

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

Para saber mais detalhes sobre como funciona a credencial e a autenticação, consulte Como lidar com a autenticação.

URL de exemplo

Esse conector é capaz de recuperar dados formatados de qualquer um dos pontos de extremidade da API REST do GitHub v3. Por exemplo, a consulta para efetuar pull de todas as confirmações para o repositório de Conectores de Dados seria semelhante a esta:

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