Compartir a través de

Ejemplo de conector de GitHub

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

Antes de empezar a crear una extensión M, debe registrar una nueva aplicación en GitHub y reemplazar los client_id archivos y client_secret por los valores adecuados de 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 de usar su compatibilidad con la versión de IE que usa este control, lo que le impedirá completar la concesión de permisos para la aplicación si se ejecuta desde Visual Studio. Una alternativa es cargar la extensión con Power BI Desktop y completar el primer flujo de OAuth allí. Una vez que se haya concedido acceso a la aplicación 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 crea 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 los access_token y refresh_token en su nombre.

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.

Al especificar una dirección URL y GitHub se autentica correctamente y concede permisos, GitHub redirigirá a Power BI al punto de conexión oauthredirect, de manera 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 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 OAuth registrada se le asigna un identificador de cliente único y un secreto de cliente. El secreto de cliente no debe compartirse. 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 (client_id archivo) y el secreto de cliente (client_secret archivo).

Implementación de OAuth en GitHub

Este ejemplo le guía por los pasos siguientes:

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

Paso 1: Creación de 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 para mostrar 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 M pueda iniciar el flujo de OAuth

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

Nombre Tipo Description
ID de cliente cuerda / cadena Obligatorio. Identificador de cliente que recibió de GitHub cuando se registró.
URI de redirección cuerda / cadena La dirección URL de la aplicación donde se enviarán los usuarios después de la autorización. Consulte los detalles siguientes sobre las direcciones URL de redireccionamiento. Para las extensiones M, debe redirect_uri ser "https://oauth.powerbi.com/views/oauthredirect.html".
scope cuerda / cadena Una lista separada por comas de ámbitos. Si no se proporciona, el ámbito tiene como valor predeterminado 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 tienen un token válido para la aplicación, el usuario no mostrará 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.
estado cuerda / cadena Una secuencia aleatoria indescifrable. Se usa para protegerse frente a ataques de falsificación de solicitudes entre sitios.

En el fragmento de código siguiente se describe cómo implementar una StartLogin función para iniciar el flujo de inicio de sesión. Una StartLogin función toma un resourceUrlvalor , statey 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: obtiene 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". Esto establece el ámbito de autorización (es decir, a lo que la aplicación quiere acceder) para el usuario.
  • state: valor interno que pasa el motor M.
  • redirect_uri: se establece 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 (identificado por su client_id valor), verá una página que les pide que conceda acceso a la aplicación. Los intentos de inicio de sesión posteriores solicitarán sus credenciales.

Paso 3: Conversión del código recibido de GitHub en un access_token

Si el usuario completa el flujo de autenticación, GitHub redirige de nuevo a la URL de redireccionamiento de Power BI con un código temporal en un parámetro code, así como el estado que proporcionó en el paso anterior en un parámetro state. La FinishLogin función extraerá el código del callbackUri parámetro y, a continuación, lo intercambiará por un token de acceso (mediante la TokenMethod función ).

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 TokenMethod función, formulas una solicitud POST al endpoint access_token de GitHub (https://github.com/login/oauth/access_token). Los parámetros siguientes son necesarios para el punto de conexión de GitHub:

Nombre Tipo Description
ID de cliente cuerda / cadena Obligatorio. Identificador de cliente que recibió de GitHub cuando se registró.
secreto_del_cliente cuerda / cadena Obligatorio. Secreto de cliente que recibió de GitHub cuando se registró.
código cuerda / cadena Obligatorio. El código que recibió en FinishLogin.
URI de redirección cuerda / cadena La dirección URL de la aplicación donde se enviarán los usuarios después de la autorización. Consulte los detalles siguientes sobre las direcciones URL de redireccionamiento.

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

Argument Description Importancia
URL 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
Query 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 = código
redirect_uri = redirect_uri
]
))
Where
  • client_id: ID de cliente de la página de la aplicación en 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 URL en tu aplicación donde serán enviados los usuarios después de la autorización.
Headers 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 TokenMethod función 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 TokenMethod método 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: Definición de funciones que acceden a la API de GitHub

El siguiente fragmento de código exporta dos funciones (GithubSample.Contents y GithubSample.PagedTable) marcandolas como sharedy las asocia al GithubSample tipo de origen de datos.

[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 GithubSample.Contents función 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 Url.Type tipo descrito.

Al asociar estas funciones con el tipo de GithubSample origen de datos, usarán automáticamente las credenciales proporcionadas por el usuario. Cualquier función de biblioteca M que se haya habilitado para la 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.

Direcció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 tendría este aspecto:

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