Поделиться через

Пример соединителя GitHub

Расширение GitHub M показывает, как добавить поддержку потока проверки подлинности протокола OAuth 2.0. Дополнительные сведения об особенностях потока проверки подлинности GitHub можно узнать на сайте документации GitHub.

Прежде чем приступить к созданию расширения M, необходимо зарегистрировать новое приложение на сайте GitHub и заменить client_idclient_secret их соответствующими значениями для приложения.

Обратите внимание на проблемы совместимости в Visual Studio:Пакет SDK Power Query использует элемент управления на основе Internet Explorer для всплывающих диалогов OAuth. GitHub прекратил поддержку версии IE, используемой этим элементом управления, что мешает вам завершить предоставление разрешения для вашего приложения при запуске в Visual Studio. Альтернативой является загрузка расширения с помощью Power BI Desktop и завершение первого потока OAuth там. После предоставления приложению доступа к вашей учетной записи последующие входы в систему будут работать нормально из Visual Studio.

OAuth и Power BI

OAuth — это форма делегирования учетных данных. Войдя в GitHub и авторизовав «приложение», которое вы создаете для GitHub, пользователь позволяет вашему «приложению» входить от его имени, чтобы получать данные в Power BI. Приложение должно получить права на получение данных (access_token) и на обновление данных по расписанию (получение и использование refresh_token). Приложение в этом контексте — это соединитель данных, используемый для выполнения запросов в Power BI. Power BI хранит и управляет access_token и refresh_token от вашего имени.

Замечание

Чтобы разрешить Power BI получать и использовать access_token, необходимо указать URL-адрес перенаправления как https://oauth.powerbi.com/views/oauthredirect.html.

При указании этого URL-адреса, и после успешной проверки подлинности и предоставления разрешений GitHub, произойдет перенаправление на конечную точку oauthredirect Power BI, чтобы Power BI мог получить access_token и refresh_token.

Регистрация приложения GitHub

Расширение Power BI должно войти в GitHub. Для этого зарегистрируйте новое приложение OAuth на сайте GitHub https://github.com/settings/applications/new.

  1. Application name: введите имя приложения для расширения M.
  2. Authorization callback URL: введите https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: в GitHub установите область на user, repo.

Замечание

Зарегистрированное приложение OAuth получает уникальный идентификатор клиента и секретный ключ клиента. Секрет клиента не должен быть общим. Идентификатор клиента и секрет клиента можно получить на странице приложения GitHub. Обновите файлы в проекте соединителя данных с помощью идентификатора клиента (client_id файла) и секрета клиента (client_secret файла).

Как реализовать GitHub OAuth

В этом примере описаны следующие действия.

  1. Создайте определение типа источника данных, которое объявляет его поддерживает OAuth.
  2. Укажите сведения, чтобы модуль M смог запустить поток OAuth (StartLogin).
  3. Преобразуйте код, полученный из GitHub, в access_token (FinishLogin и TokenMethod).
  4. Определите функции, обращаюющиеся к API GitHub (GithubSample.Contents).

Шаг 1. Создание определения источника данных

Соединитель данных начинается с записи , описывающей расширение, включая его уникальное имя (имя записи), поддерживаемые типы проверки подлинности и понятное отображаемое имя (метка) для источника данных. При поддержке OAuth определение содержит функции, реализующие контракт OAuth, в данном случае StartLogin и FinishLogin.

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

Шаг 2. Укажите данные, чтобы M-движок мог начать поток OAuth.

Поток OAuth GitHub начинается, когда пользователи перенаправляются на страницу https://github.com/login/oauth/authorize. Для входа пользователя необходимо указать ряд параметров запроса:

Имя Тип Description
идентификатор клиента струна Обязательно. Идентификатор клиента, полученный от GitHub при регистрации.
redirect_uri струна URL-адрес в приложении, на который пользователи будут перенаправляться после авторизации. Дополнительные сведения о URL-адресах перенаправления см. в разделе . Для расширений M redirect_uri должно быть "https://oauth.powerbi.com/views/oauthredirect.html"".
scope струна Разделенный запятыми список областей. Если не указано, область по умолчанию использует пустой список разрешений для пользователей, у которых нет действительного токена для приложения. Для пользователей, у которых уже есть действующий токен для приложения, страница авторизации OAuth со списком разрешений не будет показана. Вместо этого этот шаг потока будет автоматически завершен с теми же областями действия, которые использовались в последний раз, когда пользователь завершал поток.
государство струна Случайная строка, которую сложно угадать. Он используется для защиты от атак межсайтовой подделки запросов.

В следующем фрагменте кода описывается, как реализовать StartLogin функцию для запуска потока входа. Функция StartLogin принимает resourceUrlstateи display значение. В функции создайте AuthorizeUrl, который объединяет URL-адрес авторизации GitHub со следующими параметрами:

  • client_id: после регистрации расширения с помощью GitHub вы получите идентификатор клиента на странице приложения GitHub.
  • scope: задайте для области значение "user, repo". Это задает область авторизации (то есть то, что приложение хочет получить к доступу) для пользователя.
  • state: внутреннее значение, которое передает движок M.
  • redirect_uri: задано значение 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
            ];

Если это первый раз, когда пользователь входит в систему с вашим приложением (идентифицируется по его client_id значению), он увидит страницу с просьбой предоставить доступ вашему приложению. Последующие попытки входа будут запрашивать свои учетные данные.

Шаг 3. Преобразование кода, полученного из GitHub, в access_token

Если пользователь завершает поток проверки подлинности, GitHub перенаправляет обратно в URL-адрес перенаправления Power BI с временным кодом в code параметре, а также с тем состоянием, которое вы указали на предыдущем шаге, в параметре state. Функция FinishLogin извлекает код из callbackUri параметра, а затем обменивается им на маркер доступа (с помощью TokenMethod функции).

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

Чтобы получить токен доступа GitHub, передайте временный код из ответа авторизации GitHub. В функции TokenMethod создается запрос POST к конечной точке access_token GitHub (https://github.com/login/oauth/access_token). Для конечной точки GitHub требуются следующие параметры:

Имя Тип Description
идентификатор клиента струна Обязательно. Идентификатор клиента, полученный от GitHub при регистрации.
секрет_клиента струна Обязательно. Секрет клиента, полученный от GitHub при регистрации.
код струна Обязательно. Код, который вы получили в FinishLogin.
redirect_uri струна URL-адрес в приложении, на который пользователи будут перенаправляться после авторизации. Дополнительные сведения о URL-адресах перенаправления см. в следующих статьях.

Ниже приведены сведения об используемых параметрах для вызова Web.Contents .

Аргумент Description Ценность
URL-адрес URL-адрес веб-сайта. https://github.com/login/oauth/access_token
options Запись для управления поведением этой функции. Не используется в этом случае
Query Программное добавление параметров запроса в URL-адрес. Content = Text.ToBinary()
Uri.BuildQueryString()
[
client_id = client_id,
client_secret = client_secret,
code = код,
redirect_uri = redirect_uri
]
))
Where
  • client_id: идентификатор клиента на странице приложения GitHub.
  • client_secret: Секретный ключ клиента на странице приложения GitHub.
  • code: код авторизации в ответе GitHub.
  • redirect_uri: URL-адрес в вашем приложении, на который пользователи будут перенаправляться после авторизации.
Headers Запись с дополнительными заголовками для HTTP-запроса. Заголовки= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

В этом фрагменте кода описывается, как реализовать TokenMethod функцию для обмена кода авторизации на токен доступа.

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;

Ответ JSON из службы будет содержать поле access_token. Метод TokenMethod преобразует ответ JSON в запись M с помощью Json.Document и возвращает его в обработчик.

Пример ответа:

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

Шаг 4. Определение функций, обращаюющихся к API GitHub

Следующий фрагмент кода экспортирует две функции (GithubSample.Contents и GithubSample.PagedTable) помечая их как sharedи связывает их с типом 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);

Функция GithubSample.Contents также публикуется в пользовательском интерфейсе (позволяя ему отображаться в диалоговом окне получения данных ). Функция Value.ReplaceType используется для задания параметра функции типу, заданному атрибутом Url.Type .

При связывании этих функций с типом GithubSample источника данных они автоматически будут использовать учетные данные, предоставленные пользователем. Все функции библиотеки M, которые были включены для расширяемости (например, Web.Contents), автоматически наследуют эти учетные данные.

Дополнительные сведения о том, как работают учетные данные и проверка подлинности, см. в разделе "Обработка проверки подлинности".

Пример URL-адреса

Этот соединитель может получить отформатированные данные из любой конечной точки REST API GitHub версии 3. Например, запрос на извлечение всех коммитов в репозиторий Data Connectors будет выглядеть следующим образом:

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