TripPin — część 1 — łącznik danych dla usługi OData

Ten wieloczęściowy samouczek obejmuje tworzenie nowego rozszerzenia źródła danych dla dodatku Power Query. Samouczek ma być wykonywany sekwencyjnie — każda lekcja opiera się na łączniku utworzonym w poprzednich lekcjach, przyrostowo dodając nowe możliwości do łącznika.

W tej lekcji wykonasz następujące lekcji:

Tworzenie podstawowego łącznika OData

W tej sekcji utworzysz nowy projekt data Połączenie or, podaj podstawowe informacje i przetestujesz go w zestawie SDK dodatku Power Query.

Otwórz Visual Studio Code. Zalecamy utworzenie nowego obszaru roboczego, a następnie utworzenie nowego projektu rozszerzenia. Aby utworzyć nowy projekt rozszerzenia, otwórz eksploratora i w sekcji Zestaw SDK dodatku Power Query wybierz przycisk Utwórz projekt rozszerzenia.

Po wybraniu tego przycisku zostanie wyświetlony monit o wprowadzenie nazwy nowego projektu. Nadaj nowej nazwie nowy projekt TripPin.

Otwórz plik TripPin.pq i wklej następującą definicję łącznika.

section TripPin;

[DataSource.Kind="TripPin", Publish="TripPin.Publish"]
shared TripPin.Feed = Value.ReplaceType(TripPinImpl, type function (url as Uri.Type) as any);

TripPinImpl = (url as text) =>
    let
        source = OData.Feed(url)
    in
        source;

// Data Source Kind description
TripPin = [
    Authentication = [
        Anonymous = []
    ],
    Label = "TripPin Part 1 - OData"
];

// Data Source UI publishing description
TripPin.Publish = [
    Beta = true,
    Category = "Other",
    ButtonText = { "TripPin OData", "TripPin OData" }
];

Ta definicja łącznika zawiera:

• Rekord definicji źródła danych dla łącznika TripPin
• Deklaracja niejawna (anonimowa) jest jedynym typem uwierzytelniania dla tego źródła
• Funkcja (TripPinImpl) z implementacją, która wywołuje metodę OData.Feed
• Funkcja udostępniona (TripPin.Feed), która ustawia typ parametru na Uri.Type
• Rekord publikowania źródła danych, który umożliwia łącznikowi wyświetlenie w oknie dialogowym Pobieranie danych dodatku Power Query

Otwórz plik TripPin.query.pq. Zastąp bieżącą zawartość wywołaniem wyeksportowanej funkcji.

TripPin.Feed("https://services.odata.org/v4/TripPinService/")

Przed przetestowaniem łącznika należy go skompilować. W tym celu przejdź do terminalu i wybierz opcję Uruchom zadanie kompilacji... (skrót klawiaturowy Ctrl + Shift + B). Zalecamy wybranie opcji MakePQX , ale każda opcja dostępna do kompilowania powinna działać.

Wynik tej operacji tworzy nowy folder Bin , w którym skompilowany łącznik jest przechowywany jako TripPin.mez.

Plik <project.query.pq> służy do testowania rozszerzenia bez konieczności wdrażania go w folderze bin programu Power BI Desktop. Korzystanie z narzędzi dostępnych w zestawie SDK dodatku Power Query:

1. Wybierz opcję Ustaw poświadczenia.
2. Wybierz pozycję TripPin jako źródło danych.
3. Wybierz plik TripPin.query.pq jako plik query/test.
4. Wybierz opcję Anonimowy jako rodzaj uwierzytelniania.

W oknie dialogowym danych wyjściowych zostanie wyświetlony komunikat z potwierdzeniem, że ustawiono poświadczenia dla źródła danych i szczegóły dla każdego utworzonego poświadczenia.

Poświadczenie jest teraz dostępne, po wybraniu pliku TripPin.query.pq i zaznacz go prawym przyciskiem w dokumencie, aby ocenić bieżący plik dodatku Power Query lub użyć opcji Ocena bieżącego pliku z narzędzi zestawu SDK dodatku Power Query.

W oknie dialogowym danych wyjściowych zostanie wyświetlony komunikat wyników oceny, a także nowe okno o nazwie PQTest wynik.

Okno wyników PQTest składa się z trzech kart:

• Dane wyjściowe: wyświetla podgląd danych w siatce.
• Podsumowanie: ogólne szczegóły oceny, takie jak StartTime, EndTime, Duration, plik, który został użyty do oceny, stanu i nie tylko.
• Źródło danych: zawiera informacje o źródle danych, które zostało użyte z typu, nazwy funkcji i ścieżki.

Możesz wypróbować kilka różnych adresów URL OData w pliku testowym, aby zobaczyć, jak są zwracane różne wyniki. Na przykład:

• https://services.odata.org/v4/TripPinService/Me
• https://services.odata.org/v4/TripPinService/GetPersonWithMostFriends()
• https://services.odata.org/v4/TripPinService/People

Plik TripPin.query.pq może zawierać pojedyncze instrukcje, instrukcje let lub pełne dokumenty sekcji.

let
    Source = TripPin.Feed("https://services.odata.org/v4/TripPinService/"),
    People = Source{[Name="People"]}[Data],
    SelectColumns = Table.SelectColumns(People, {"UserName", "FirstName", "LastName"})
in
    SelectColumns

Otwórz program Fiddler , aby przechwycić ruch HTTP i uruchomić zapytanie. Powinno zostać wyświetlonych kilka różnych żądań do services.odata.org wygenerowanych przez proces kontenera mashup. Zobaczysz, że uzyskanie dostępu do głównego adresu URL usługi powoduje wyświetlenie stanu 302 i przekierowanie do dłuższej wersji adresu URL. Następujące przekierowania to inne zachowanie, które otrzymujesz "za darmo" z funkcji biblioteki podstawowej.

Jedną z rzeczy, które należy zauważyć, jeśli spojrzysz na adresy URL, jest to, że można zobaczyć składanie zapytań, które wystąpiło w instrukcji SelectColumns . https://services.odata.org/v4/TripPinService/People?$select=UserName%2CFirstName%2CLastName

Jeśli dodasz więcej przekształceń do zapytania, zobaczysz, jak wpływają one na wygenerowany adres URL.

To zachowanie jest ważne. Mimo że nie zaimplementowaliśmy jawnej logiki składania, łącznik dziedziczy te możliwości z funkcji OData.Feed . Instrukcje języka M są w stanie tworzyć — konteksty filtru będą przepływać z jednej funkcji do innej, jeśli jest to możliwe. Jest to podobne do sposobu, w jaki funkcje źródła danych używane w łączniku dziedziczą kontekst uwierzytelniania i poświadczenia. W kolejnych lekcjach zastąpisz użycie biblioteki OData.Feed, która ma natywne możliwości składania, na wartość Web.Contents, która nie. Aby uzyskać ten sam poziom możliwości, należy użyć interfejsu Table.View i zaimplementować własną jawną logikę składania.

Ładowanie rozszerzenia w programie Power BI Desktop

Aby użyć rozszerzenia w programie Power BI Desktop, musisz skopiować plik wyjściowy projektu łącznika (TripPin.mez) do katalogu Custom Połączenie ors.

1. Utwórz katalog [Moje dokumenty]\Power BI Desktop\Custom Połączenie ors.
2. Skopiuj plik rozszerzenia (TripPin.mez) do tego katalogu.
3. Zaznacz opcję (Niezalecane) Zezwalaj na ładowanie dowolnego rozszerzenia bez walidacji lub ostrzeżenia w programie Power BI Desktop (w obszarze Opcje plików>i ustawienia>Opcje rozszerzenia>danych zabezpieczeń).>
4. Uruchom ponownie program Power BI Desktop.
5. Wybierz pozycję Pobierz dane > Więcej , aby wyświetlić okno dialogowe Pobieranie danych .

Rozszerzenie można zlokalizować, wpisując jego nazwę w polu wyszukiwania.

Wybierz nazwę funkcji i wybierz pozycję Połączenie. Zostanie wyświetlony komunikat innej firmy — wybierz pozycję Kontynuuj , aby kontynuować. Zostanie wyświetlone okno dialogowe wywołania funkcji. Wprowadź główny adres URL usługi (https://services.odata.org/v4/TripPinService/), a następnie wybierz przycisk OK.

Ponieważ po raz pierwszy uzyskujesz dostęp do tego źródła danych, otrzymasz monit o podanie poświadczeń. Sprawdź, czy zaznaczono najkrótszy adres URL, a następnie wybierz pozycję Połączenie.

Zwróć uwagę, że zamiast uzyskać prostą tabelę danych, zostanie wyświetlony nawigator. Wynika to z faktu , że funkcja OData.Feed zwraca tabelę ze specjalnymi metadanymi na jego podstawie, że środowisko dodatku Power Query wie, że jest wyświetlane jako tabela nawigacji. W tym przewodniku opisano sposób tworzenia i dostosowywania własnej tabeli nawigacji w przyszłej lekcji.

Wybierz tabelę Me , a następnie wybierz pozycję Przekształć dane. Zwróć uwagę, że kolumny mają już przypisane typy (dobrze, większość z nich). Jest to kolejna funkcja bazowej funkcji OData.Feed . Jeśli obserwujesz żądania w programie Fiddler, zobaczysz, że pobrano dokument $metadata usługi. Implementacja OData aparatu automatycznie określa schemat, typy danych i relacje usługi.

Podsumowanie

W tej lekcji przedstawiono proces tworzenia prostego łącznika opartego na funkcji biblioteki OData.Feed . Jak widać, do włączenia w pełni funkcjonalnego łącznika za pośrednictwem funkcji podstawowej potrzebna jest mała logika OData . Inne funkcje z włączoną rozszerzalnością, takie jak ODBC. Źródło danych zapewnia podobne możliwości.

W następnej lekcji zastąp użycie funkcji OData.Feed funkcją o mniejszej możliwości — Web.Contents. Każda lekcja implementuje więcej funkcji łącznika, w tym stronicowanie, wykrywanie metadanych/schematów i składanie zapytań do składni zapytań OData, dopóki łącznik niestandardowy nie obsługuje tego samego zakresu możliwości co OData.Feed.

Następne kroki

TripPin — część 2 — Połączenie danych dla usługi REST