Compartir a través de

Ejemplo de conector de GitHub

  • Artículo

La extensión M de GitHub muestra cómo agregar compatibilidad con un flujo de autenticación de protocolo OAuth 2.0. Puede obtener más información sobre los detalles del flujo de autenticación de GitHub en el sitio para desarrolladores de GitHub.

Antes de empezar a crear una extensión M, debe registrar una nueva aplicación en GitHub y reemplazar los archivos client_id y client_secret por los valores adecuados para la aplicación.

Nota sobre los problemas de compatibilidad en Visual Studio: El SDK de Power Query usa un control basado en Internet Explorer para mostrar diálogos de OAuth. GitHub ha dejado en desuso su compatibilidad con la versión de IE que este control usa, lo que le impedirá completar la concesión de permisos para su aplicación si se ejecuta desde Visual Studio. Una alternativa consiste en cargar la extensión con Power BI Desktop y completar el primer flujo de OAuth allí. Una vez que se haya concedido a la aplicación acceso a su cuenta, los inicios de sesión posteriores funcionarán correctamente desde Visual Studio.

OAuth y Power BI

OAuth es una forma de delegación de credenciales. Al iniciar sesión en GitHub y autorizar la "aplicación" que usted cree para GitHub, el usuario permite que la "aplicación" inicie sesión en su nombre para recuperar datos en Power BI. Se deben conceder derechos a la "aplicación" para recuperar datos (obtener un access_token) y actualizar los datos según una programación (obtener y usar un refresh_token). La "aplicación" en este contexto es el conector de datos que se usa para ejecutar consultas en Power BI. Power BI almacena y administra el access_token y el refresh_token en nombre de usted.

Nota:

Para permitir que Power BI obtenga y use el access_token, debe especificar la dirección URL de redireccionamiento como https://oauth.powerbi.com/views/oauthredirect.html.

Cuando se especifica esta dirección URL y GitHub autentica correctamente y concede permisos, GitHub le redirigirá al punto de conexión oauthredirect de PowerBI para que Power BI pueda recuperar el access_token y el refresh_token.

Registro de una aplicación de GitHub

La extensión de Power BI debe iniciar sesión en GitHub. Para habilitarlo, registre una nueva aplicación de OAuth con GitHub en https://github.com/settings/applications/new.

  1. Application name: escriba un nombre para la aplicación para la extensión M.
  2. Authorization callback URL: escriba https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: en GitHub, establezca el ámbito en user, repo.

Nota:

A una aplicación de OAuth que se registra se le asigna un identificador de cliente y un secreto de cliente únicos. El secreto de cliente no puede compartirse. Usted obtiene el identificador de cliente y el secreto de cliente de la página de la aplicación de GitHub. Actualice los archivos del proyecto del conector de datos con el identificador de cliente (archivo client_id) y el secreto de cliente (archivo client_secret).

Implementación de OAuth en GitHub

Este ejemplo le guiará a través de los siguientes pasos:

  1. Crear una definición de tipo de origen de datos que declare que admite OAuth.
  2. Proporcionar detalles para que el motor de M pueda iniciar el flujo de OAuth (StartLogin).
  3. Convertir el código recibido de GitHub en un access_token (FinishLogin y TokenMethod).
  4. Definir funciones que accedan a la API de GitHub (GithubSample.Contents).

Paso 1: Crear una definición de origen de datos

Un conector de datos comienza con un registro que describe la extensión, incluido su nombre único (que es el nombre del registro), los tipos de autenticación admitidos y un nombre de visualización descriptivo (etiqueta) para el origen de datos. Al admitir OAuth, la definición contiene las funciones que implementan el contrato de OAuth, en este caso, StartLogin y FinishLogin.

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

Paso 2: Proporcionar detalles para que el motor de M pueda iniciar el flujo de OAuth

El flujo de OAuth de GitHub se inicia cuando se dirige a los usuarios a la página https://github.com/login/oauth/authorize. Para que el usuario inicie sesión, debe especificar una serie de parámetros de consulta:

Nombre Escribir Descripción
client_id string Necesario. Identificador de cliente que recibió de GitHub al registrarse.
redirect_uri string La dirección URL de su aplicación a donde se enviará a los usuarios después de la autorización. Vea los detalles siguientes sobre las URL de redireccionamiento. Para las extensiones M, el redirect_uri debe ser "https://oauth.powerbi.com/views/oauthredirect.html".
scope string Lista de ámbitos separados por comas. Si no se proporciona, el ámbito predeterminado es una lista vacía de ámbitos para los usuarios que no tienen un token válido para la aplicación. Para los usuarios que ya dispongan de un token válido para la aplicación, el usuario no se mostrará en la página de autorización de OAuth con la lista de ámbitos. En su lugar, este paso del flujo se completará automáticamente con los mismos ámbitos que se usaron la última vez que el usuario completó el flujo.
state string Una secuencia aleatoria indescifrable. Se utiliza para protegerte contra los ataques de falsificación de solicitudes entre sitios.

En el fragmento de código siguiente se describe cómo implementar una función StartLogin para iniciar el flujo de inicio de sesión. Una función StartLogin toma un valor resourceUrl, state y display. En la función, cree un AuthorizeUrl que concatene la dirección URL de autorización de GitHub con los parámetros siguientes:

  • client_id: obtendrá el identificador de cliente después de registrar la extensión en GitHub desde la página de la aplicación de GitHub.
  • scope: establezca el ámbito en "user, repo". De esta manera se establece el ámbito de autorización (es decir, a lo que la aplicación quiere acceder) para el usuario.
  • state: valor interno que el motor M pasa.
  • redirect_uri: establézcalo en 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
            ];

Si es la primera vez que el usuario inicia sesión con la aplicación (lo que se identifica mediante su valor de client_id), verá una página que le pide que conceda acceso a la aplicación. Los intentos de inicio de sesión posteriores simplemente solicitarán sus credenciales.

Paso 3: Convertir el código recibido de GitHub en un access_token

Si el usuario finaliza el flujo de autenticación, GitHub le redirecciona de vuelta a la dirección URL de redireccionamiento con un código temporal en un parámetro code así como con el estado que se haya proporcionado en el paso anterior en un parámetro state. La función FinishLogin extraerá el código del parámetro callbackUri y, a continuación, lo intercambiará por un token de acceso (mediante la función TokenMethod).

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

Para obtener un token de acceso de GitHub, pase el código temporal de la respuesta de autorización de GitHub. En la función TokenMethod, debe formular una solicitud POST al punto de conexión de access_token de GitHub (https://github.com/login/oauth/access_token). Los siguientes parámetros son necesarios para el punto de conexión de GitHub:

Nombre Escribir Descripción
client_id string Necesario. Identificador de cliente que recibió de GitHub al registrarse.
client_secret string Necesario. Secreto de cliente que recibió de GitHub al registrarse.
code string Necesario. El código que recibió en FinishLogin.
redirect_uri string La dirección URL de su aplicación a donde se enviará a los usuarios después de la autorización. Vea los detalles siguientes sobre las URL de redireccionamiento.

Estos son los parámetros usados para la llamada Web.Contents.

Argumento Descripción Valor
dirección url La dirección URL del sitio web. https://github.com/login/oauth/access_token
options Un registro para controlar el comportamiento de esta función. No se usa en este caso.
Consultar Agregue mediante programación parámetros de consulta a la dirección URL. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Where
  • client_id: identificador de cliente de la página de la aplicación de GitHub.
  • client_secret: secreto de cliente de la página de la aplicación de GitHub.
  • code: código en la respuesta de autorización de GitHub.
  • redirect_uri: la dirección URL de su aplicación a donde se enviará a los usuarios después de la autorización.
encabezados Un registro con encabezados adicionales para la solicitud HTTP. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

Este fragmento de código describe cómo implementar una función TokenMethod para intercambiar un código de autenticación para un token de acceso.

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 respuesta JSON del servicio contendrá un campo access_token. El método TokenMethod convierte la respuesta JSON en un registro M mediante Json.Document y lo devuelve al motor.

Respuesta de ejemplo:

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

Paso 4: Definir funciones que accedan a la API de GitHub

El siguiente fragmento de código exporta dos funciones (GithubSample.Contents y GithubSample.PagedTable) marcándolas como shared y las asocia al tipo de origen de datos 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);

La función GithubSample.Contents también se publica en la interfaz de usuario (lo que permite que aparezca en el cuadro de diálogo Obtener datos). La función Value.ReplaceType se usa para establecer el parámetro de función en el tipo Url.Type atribuido.

Al asociar estas funciones con el tipo de origen de datos GithubSample, usarán automáticamente las credenciales proporcionadas por el usuario. Cualquier función de biblioteca M que se haya habilitado con fines de extensibilidad (como Web.Contents) también heredará automáticamente estas credenciales.

Para obtener más información sobre cómo funcionan las credenciales y la autenticación, consulte Control de la autenticación.

URL de ejemplo

Este conector puede recuperar datos con formato de cualquiera de los puntos de conexión de la API REST de GitHub v3. Por ejemplo, la consulta para extraer todas las confirmaciones en el repositorio conectores de datos sería como la siguiente:

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