Пример соединителя GitHub
Расширение GitHub M показывает, как добавить поддержку потока проверки подлинности протокола OAuth 2.0. Дополнительные сведения об особенностях потока проверки подлинности GitHub можно узнать на сайте разработчика GitHub.
Прежде чем приступить к созданию расширения M, необходимо зарегистрировать новое приложение на сайте GitHub и заменить client_id
client_secret
их соответствующими значениями для приложения.
Обратите внимание на проблемы совместимости в Visual Studio: пакет SDK Power Query использует элемент управления на основе Internet Explorer для всплывающих диалогов OAuth. GitHub не рекомендует свою поддержку версии IE, используемой этим элементом управления, что позволит вам завершить предоставление разрешения для приложения при запуске из Visual Studio. Альтернативой является загрузка расширения с помощью Power BI Desktop и завершение первого потока OAuth там. После предоставления приложению доступа к вашей учетной записи последующие имена входа будут работать нормально из Visual Studio.
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 успешно выполняет проверку подлинности и предоставляет разрешения, GitHub перенаправляется в конечную точку oauthredirect PowerBI, чтобы Power BI получите access_token и refresh_token.
Расширение Power BI должно войти в GitHub. Для этого зарегистрируйте новое приложение OAuth на сайте GitHub https://github.com/settings/applications/new.
Application name
: введите имя приложения для расширения M.Authorization callback URL
: ввод https://oauth.powerbi.com/views/oauthredirect.html.Scope
: в GitHub задайте дляuser, repo
области значение .
Примечание
Зарегистрированное приложение OAuth назначается уникальным идентификатором клиента и секретом клиента. Секрет клиента не должен быть общим. Идентификатор клиента и секрет клиента можно получить на странице приложения GitHub. Обновите файлы в проекте соединителя данных с помощью идентификатора клиента (client_id
файла) и секрета клиента (client_secret
файла).
В этом примере описаны следующие действия.
- Создайте определение типа источника данных, которое объявляет его поддерживает OAuth.
- Укажите сведения, чтобы модуль M смог запустить поток OAuth (
StartLogin
). - Преобразуйте код, полученный из GitHub, в access_token (
FinishLogin
иTokenMethod
). - Определите функции, обращаюющиеся к API GitHub (
GithubSample.Contents
).
Соединитель данных начинается с записи , описывающей расширение, включая его уникальное имя (имя записи), поддерживаемые типы проверки подлинности и понятное отображаемое имя (метка) для источника данных.
При поддержке OAuth определение содержит функции, реализующие контракт OAuth, в данном случае StartLogin
и FinishLogin
.
//
// Data Source definition
//
GithubSample = [
Authentication = [
OAuth = [
StartLogin = StartLogin,
FinishLogin = FinishLogin
]
],
Label = Extension.LoadString("DataSourceLabel")
];
Поток OAuth GitHub начинается при перенаправлении пользователей на страницу https://github.com/login/oauth/authorize
.
Для входа пользователя необходимо указать ряд параметров запроса:
Имя. | Тип | Описание |
---|---|---|
client_id | строка | Необходимые. Идентификатор клиента, полученный от GitHub при регистрации. |
redirect_uri | строка | URL-адрес в приложении, где пользователи будут отправляться после авторизации. См. дополнительные сведения ниже о URL-адресах перенаправления. Для расширений redirect_uri M должно быть "https://oauth.powerbi.com/views/oauthredirect.html". |
область | строка | Разделенный запятыми список областей. Если это не указано, область по умолчанию использует пустой список областей для пользователей, у которых нет допустимого маркера для приложения. Для пользователей, у которых уже есть действительный маркер для приложения, пользователь не будет отображать страницу авторизации OAuth со списком областей. Вместо этого этот шаг потока будет автоматически завершен с теми же областями, которые использовались при последнем завершении потока пользователем. |
state | string | Неугадываемая случайная строка. Он используется для защиты от атак подделки межсайтовых запросов. |
В следующем фрагменте кода описывается, как реализовать StartLogin
функцию для запуска потока входа.
Функция StartLogin
принимает resourceUrl
state
и 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
значению), он увидит страницу, которая просит предоставить им доступ к вашему приложению. Последующие попытки входа просто запрашивают свои учетные данные.
Если пользователь завершает поток проверки подлинности, 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 Authorize. В функции вы сформулируете TokenMethod
запрос POST к конечной точке access_token GitHub (https://github.com/login/oauth/access_token
).
Для конечной точки GitHub требуются следующие параметры:
Имя. | Тип | Описание |
---|---|---|
client_id | строка | Необходимые. Идентификатор клиента, полученный от GitHub при регистрации. |
client_secret | строка | Необходимые. Секрет клиента, полученный от GitHub при регистрации. |
кодом | строка | Необходимые. Полученный код FinishLogin . |
redirect_uri | строка | URL-адрес в приложении, где пользователи будут отправляться после авторизации. Дополнительные сведения о URL-адресах перенаправления см. ниже. |
Ниже приведены сведения об используемых параметрах для вызова Web.Contents .
Аргумент | Description | Значение |
---|---|---|
URL-адрес | URL-адрес веб-сайта. | https://github.com/login/oauth/access_token |
options | Запись для управления поведением этой функции. | Не используется в этом случае |
Query | Программное добавление параметров запроса в URL-адрес. | Content = Text.ToBinary() Где
|
Заголовки | Запись с дополнительными заголовками для HTTP-запроса. | Headers= [ |
В этом фрагменте кода описывается, как реализовать 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"
}
Следующий фрагмент кода экспортирует две функции (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), автоматически наследуют эти учетные данные.
Дополнительные сведения о том, как работают учетные данные и проверка подлинности, см. в разделе "Обработка проверки подлинности".
Этот соединитель может получить отформатированные данные из любой конечной точки REST API GitHub версии 3. Например, запрос для извлечения всех фиксаций в репозиторий соединителей данных будет выглядеть следующим образом:
GithubSample.Contents("https://api.github.com/repos/microsoft/dataconnectors/commits")