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

Пример соединителя 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 и 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 успешно выполняет проверку подлинности и предоставляет разрешения, GitHub перенаправляется в конечную точку oauthredirect PowerBI, чтобы 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. Предоставление сведений о запуске потока OAuth подсистемой M

Поток 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 принимает 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 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()
Uri.BuildQueryString()
[
client_id = client_id,
client_secret = client_secret,
code = код,
redirect_uri = redirect_uri
]
))
Где
  • client_id: идентификатор клиента на странице приложения GitHub.
  • client_secret: секрет клиента на странице приложения GitHub.
  • code: код в ответе авторизации GitHub.
  • redirect_uri: URL-адрес в приложении, где пользователи будут отправляться после авторизации.
Заголовки Запись с дополнительными заголовками для HTTP-запроса. Headers= [
#"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. Например, запрос для извлечения всех фиксаций в репозиторий соединителей данных будет выглядеть следующим образом:

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