Partilhar via

Exemplo de conector GitHub

  • Artigo

A extensão GitHub M mostra como adicionar suporte para 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 desenvolvedor do GitHub.

Antes de começar a criar uma extensão M, você precisa registrar um novo aplicativo no GitHub e substituir os client_id arquivos 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 exibir 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 executado de dentro do Visual Studio. Uma alternativa é carregar a extensão com o Power BI Desktop e concluir o primeiro fluxo OAuth lá. Depois que seu aplicativo tiver recebido acesso à sua conta, os logons subsequentes funcionarão bem a partir do Visual Studio.

OAuth e Power BI

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

Nota

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 êxito, 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 login no GitHub. Para habilitar isso, você registra um novo aplicativo OAuth com o GitHub em https://github.com/settings/applications/new.

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

Nota

Um aplicativo OAuth registrado recebe uma ID de Cliente e um Segredo de Cliente exclusivos. O Segredo do Cliente não deve ser partilhado. 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 Data Connector com a ID do Cliente (client_id arquivo) e o Segredo do Cliente (client_secret arquivo).

Como implementar o GitHub OAuth

Este exemplo irá guiá-lo pelas seguintes etapas:

  1. Crie uma definição de Tipo de Fonte de Dados que declare que ela oferece suporte a OAuth.
  2. Forneça detalhes para que o mecanismo M possa iniciar o fluxo 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), tipo(s) de autenticação suportado(s) e um nome de exibição amigável (rótulo) para a fonte de dados. Ao oferecer suporte ao 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")
];

Etapa 2 - Fornecer detalhes para que o motor M possa iniciar o fluxo OAuth

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

Nome Tipo Description
client_id string Necessário. O ID do cliente que você recebeu do GitHub quando se registrou.
redirect_uri string O URL no seu aplicativo para onde os usuários serão enviados após a autorização. Veja detalhes abaixo sobre urls de redirecionamento. Para extensões M, o redirect_uri deve ser "https://oauth.powerbi.com/views/oauthredirect.html".
âmbito string Uma lista de escopos separados por vírgula. Se não for fornecido, o escopo assume 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, não será mostrada a página de autorização OAuth com a lista de escopos. Em vez disso, essa etapa do fluxo será concluída automaticamente com os mesmos escopos que foram usados da última vez que o usuário concluiu o fluxo.
state string Uma cadeia de caracteres aleatória imadivinhável. Ele é usado para proteger contra ataques de falsificação de solicitação entre sites.

O trecho de código a seguir descreve como implementar uma StartLogin função para iniciar o fluxo de login. Uma StartLogin função tem um resourceUrl, statee display valor. 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 o 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 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 esta for a primeira vez que o utilizador inicia sessão com a sua aplicação (identificada pelo respetivo client_id valor), verá uma página que lhe pede para conceder acesso à sua aplicação. As tentativas de login subsequentes simplesmente 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 callbackUri código do parâmetro e, em seguida, 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 do GitHub, passe o código temporário da Resposta de Autorização do GitHub. TokenMethod Na função, você formula uma solicitação POST para o ponto de extremidade access_token do GitHub (https://github.com/login/oauth/access_token). Os seguintes parâmetros são necessários para o ponto de extremidade GitHub:

Nome Tipo Description
client_id string Necessário. O ID do cliente que você recebeu do GitHub quando se registrou.
client_secret string Necessário. O segredo do cliente que você recebeu do GitHub quando se registrou.
code string Necessário. O código que você recebeu em FinishLogin.
redirect_uri string O URL no seu aplicativo para onde os usuários serão enviados após a autorização. Veja detalhes abaixo sobre URLs de redirecionamento.

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

Argumento Description valor
url A 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. Conteúdo = Text.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 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: O URL no seu aplicativo para onde os usuários serão enviados após a autorização.
Cabeçalhos Um registro com cabeçalhos adicionais para a solicitação HTTP. Cabeçalhos= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Aceitar" = "application/json"
]

Este trecho 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.

Exemplo de resposta:

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

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

O trecho de código a seguir exporta duas funções (GithubSample.Contents e GithubSample.PagedTable) marcando-as como shared, e as associa 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 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 function para o Url.Type tipo atribuído.

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

Para obter mais detalhes sobre como a credencial e a autenticação funcionam, consulte Manipulando 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 extrair todas as confirmações para o repositório Data Connectors teria esta aparência:

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