GitHub Bağlayıcı örneği

Makale
07/04/2024

GitHub M uzantısı, OAuth 2.0 protokolü kimlik doğrulama akışı için nasıl destek ekleneceğini gösterir. GitHub Geliştirici sitesinde GitHub'ın kimlik doğrulama akışının ayrıntıları hakkında daha fazla bilgi edinebilirsiniz.

M uzantısı oluşturmaya başlamadan önce GitHub'a yeni bir uygulama kaydetmeniz ve ve client_secret dosyalarını uygulamanız için uygun değerlerle değiştirmeniz client_id gerekir.

Visual Studio'daki uyumluluk sorunlarına dikkat edin: Power Query SDK'sı, OAuth iletişim kutularını açmak için Internet Explorer tabanlı bir denetim kullanır. GitHub, bu denetim tarafından kullanılan IE sürümü desteğini kullanım dışı bırakmıştır. Bu, Visual Studio içinden çalıştırıldığında uygulamanız için izin verme işlemini tamamlamanızı engeller. Alternatif olarak uzantıyı Power BI Desktop ile yükleyebilir ve ilk OAuth akışını orada tamamlayabilirsiniz. Uygulamanıza hesabınıza erişim verildikten sonra, sonraki oturum açma işlemleri Visual Studio'dan sorunsuz çalışır.

OAuth ve Power BI

OAuth bir kimlik bilgisi temsilcisi biçimidir. GitHub'da oturum açarak ve GitHub için oluşturduğunuz "uygulamayı" yetkileyerek, kullanıcı "uygulamanızın" Power BI'a veri almak için kendi adına oturum açmasına izin verir. "Uygulamaya" verileri alma (access_token alma) ve verileri bir zamanlamaya göre yenileme (refresh_token alma ve kullanma) hakları verilmelidir. Bu bağlamdaki "uygulamanız", Power BI içinde sorgu çalıştırmak için kullanılan Veri Bağlayıcınızdır. Power BI, access_token ve refresh_token sizin yerinize depolar ve yönetir.

Not

Power BI'ın access_token almasına ve kullanmasına izin vermek için yeniden yönlendirme url'sini olarak https://oauth.powerbi.com/views/oauthredirect.htmlbelirtmeniz gerekir.

Bu URL'yi belirttiğinizde Ve GitHub başarıyla kimlik doğrulaması yapıp izinler verdiğinde, GitHub Power BI'ın access_token ve refresh_token alabilmesi için PowerBI'ın oauthredirect uç noktasına yönlendirilir.

GitHub uygulamasını kaydetme

Power BI uzantınızın GitHub'da oturum açması gerekir. Bunu etkinleştirmek için adresinde GitHub'a https://github.com/settings/applications/newyeni bir OAuth uygulaması kaydedersiniz.

Application name: M uzantınız için uygulama için bir ad girin.
Authorization callback URL: girin https://oauth.powerbi.com/views/oauthredirect.html.
Scope: GitHub'da kapsamı olarak user, repoayarlayın.

Not

Kayıtlı bir OAuth uygulamasına benzersiz bir İstemci Kimliği ve İstemci Gizli Anahtarı atanır. gizli dizi paylaşılmamalıdır. GitHub uygulama sayfasından İstemci Kimliği ve İstemci Gizli Anahtarı'nı alırsınız. Veri Bağlayıcısı projenizdeki dosyaları İstemci Kimliği ( dosya) ve İstemci Gizli Anahtarı (client_idclient_secret dosyası) ile güncelleştirin.

GitHub OAuth'u uygulama

Bu örnek aşağıdaki adımlarda size yol gösterecektir:

OAuth'u desteklediğini bildiren bir Veri Kaynağı Türü tanımı oluşturun.
M altyapısının OAuth akışını (StartLogin ) başlatabilmesi için ayrıntıları sağlayın.
GitHub'dan alınan kodu bir access_token (FinishLogin ve TokenMethod) dönüştürün.
GitHub API'sine (GithubSample.Contents ) erişen işlevleri tanımlayın.

1. Adım - Veri Kaynağı tanımı oluşturma

Veri Bağlayıcısı, benzersiz adı (kaydın adı), desteklenen kimlik doğrulama türleri ve veri kaynağı için kolay görünen ad (etiket) dahil olmak üzere uzantıyı açıklayan bir kayıtla başlar. OAuth'u desteklerken tanım, OAuth sözleşmesini uygulayan işlevleri (bu örnekte StartLogin ve FinishLogin) içerir.

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

2. Adım - M altyapısının OAuth akışını başlatabilmesi için ayrıntıları sağlayın

GitHub OAuth akışı, kullanıcıları sayfaya https://github.com/login/oauth/authorize yönlendirdiğinizde başlar. Kullanıcının oturum açması için bir dizi sorgu parametresi belirtmeniz gerekir:

Adı	Tür	Açıklama
client_id	Dize	Gerekli. Kaydolduğunda GitHub'dan aldığınız istemci kimliği.
redirect_uri	Dize	Uygulamanızda kullanıcıların yetkilendirmeden sonra gönderileceği URL. Yeniden yönlendirme URL'leri hakkındaki ayrıntılara bakın. M uzantıları `redirect_uri` için "https://oauth.powerbi.com/views/oauthredirect.html".
kapsam	Dize	Virgülle ayrılmış kapsam listesi. Sağlanmadıysa, kapsam varsayılan olarak uygulama için geçerli bir belirteci olmayan kullanıcılar için boş bir kapsam listesidir. Uygulama için geçerli bir belirteci olan kullanıcılar için, kullanıcıya kapsam listesini içeren OAuth yetkilendirme sayfası gösterilmez. Bunun yerine, akışın bu adımı, kullanıcı akışı son tamamladığınızda kullanılan kapsamlarla otomatik olarak tamamlanır.
semt	Dize	Tahmin edilemeyen bir rastgele dize. Siteler arası istek sahteciliği saldırılarına karşı koruma sağlamak için kullanılır.

Aşağıdaki kod parçacığında, oturum açma akışını başlatmak için bir StartLogin işlevin nasıl uygulandığı açıklanmaktadır. İşlev StartLogin , resourceUrlstateve display değerini alır. işlevinde GitHub yetkilendirme URL'sini aşağıdaki parametrelerle birleştirir AuthorizeUrl :

client_id: Uzantınızı GitHub'a kaydettikten sonra GitHub uygulama sayfasından istemci kimliğini alırsınız.
scope: Kapsamı "user, repo" olarak ayarlayın. Bu, kullanıcı için yetkilendirme kapsamını (yani uygulamanızın erişmek istediği öğeyi) ayarlar.
state: M altyapısının geçirdiği iç değer.
redirect_uri: olarak https://oauth.powerbi.com/views/oauthredirect.htmlayarlayın.

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
            ];

Kullanıcı uygulamanızla ilk kez oturum açıyorsa (değeriyle client_id tanımlanır), uygulamanıza erişim izni vermesini isteyen bir sayfa görür. Sonraki oturum açma girişimleri yalnızca kimlik bilgilerini ister.

3. Adım : GitHub'dan alınan kodu bir access_token dönüştürme

Kullanıcı kimlik doğrulama akışını tamamlarsa GitHub, bir parametrede geçici bir kod ve bir parametrenin önceki adımında code sağladığınız durum ile Power BI yeniden yönlendirme URL'sine state yeniden yönlendirir. İşleviniz FinishLogin , kodu parametresinden callbackUri ayıklar ve ardından bir erişim belirteci (işlevini kullanarak TokenMethod ) ile değiştirir.

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

GitHub erişim belirteci almak için GitHub Yetkilendirme Yanıtı'ndan geçici kodu geçirirsiniz. işlevinde TokenMethod GitHub'ın access_token uç noktasına (https://github.com/login/oauth/access_token) bir POST isteği formüle edersiniz. GitHub uç noktası için aşağıdaki parametreler gereklidir:

Adı	Tür	Açıklama
client_id	Dize	Gerekli. Kaydolduğunda GitHub'dan aldığınız istemci kimliği.
client_secret	Dize	Gerekli. Kaydolduğunda GitHub'dan aldığınız istemci gizli dizisi.
kod	Dize	Gerekli. içinde `FinishLogin`aldığınız kod.
redirect_uri	Dize	Uygulamanızda kullanıcıların yetkilendirmeden sonra gönderileceği URL. Yeniden yönlendirme URL'leri hakkındaki ayrıntılara bakın.

Web.Contents çağrısı için kullanılan parametrelerin ayrıntıları aşağıdadır.

Bağımsız değişken	Açıklama	Değer
url	Web sitesinin URL'si.	https://github.com/login/oauth/access_token
seçenekler	Bu işlevin davranışını denetlemek için bir kayıt.	Bu durumda kullanılmaz
Sorgu	URL'ye program aracılığıyla sorgu parametreleri ekleyin.	`Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] ))` Konumu `client_id`: GitHub uygulama sayfasından istemci kimliği. `client_secret`: GitHub uygulama sayfasından istemci gizli dizisi. `code`: GitHub yetkilendirme yanıtında kod. `redirect_uri`: Uygulamanızda kullanıcıların yetkilendirmeden sonra gönderileceği URL.
Üst Bilgiler	HTTP isteği için ek üst bilgiler içeren bir kayıt.	`Headers= [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]`

Bu kod parçacığında, erişim belirteci için kimlik TokenMethod doğrulama kodu değişimine yönelik bir işlevin nasıl uygulandığı açıklanır.

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;

Hizmetten gelen JSON yanıtı bir access_token alanı içerir. yöntemi JSON.Document TokenMethodkullanarak JSON yanıtını bir M kaydına dönüştürür ve altyapıya döndürür.

Örnek yanıt:

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

4. Adım - GitHub API'sine erişen işlevleri tanımlama

Aşağıdaki kod parçacığı, iki işlevi (GithubSample.Contents ve GithubSample.PagedTable) olarak sharedişaretleyerek dışarı aktarır ve bunları Veri Kaynağı Türü ile GithubSample ilişkilendirir.

[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);

İşlev GithubSample.Contents kullanıcı arabiriminde de yayımlanır (Veri Al iletişim kutusunda görünmesine izin verir). Value.ReplaceType işlevi, işlev parametresini atfedilen türe ayarlamak için Url.Type kullanılır.

Bu işlevleri veri kaynağı türüyle GithubSample ilişkilendirerek kullanıcının sağladığı kimlik bilgilerini otomatik olarak kullanır. Genişletilebilirlik için etkinleştirilen tüm M kitaplığı işlevleri (Web.Contents gibi) bu kimlik bilgilerini de otomatik olarak devralır.

Kimlik bilgilerinin ve kimlik doğrulamasının nasıl çalıştığı hakkında daha fazla bilgi için bkz . Kimlik Doğrulamasını İşleme.

Örnek URL

Bu bağlayıcı, biçimlendirilmiş verileri GitHub v3 REST API uç noktalarının herhangi birinden alabilir. Örneğin, Veri Bağlayıcıları deposuna tüm işlemeleri çekme sorgusu şöyle görünür:

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

Aracılığıyla paylaş