Interfejs API sieci szkieletowej dla widoku schematu i eksploratora schematu graphQL

Interfejs Fabric API dla języka GraphQL automatycznie generuje schemat definiujący strukturę interfejsu API na podstawie połączonych źródeł danych. Schemat napisany w języku GraphQL Schema Definition Language (SDL) opisuje wszystkie dostępne typy, pola, zapytania i mutacje, których klienci mogą używać do interakcji z danymi.

Widok schematu zapewnia widok tylko do odczytu, oparty na tekście kompletnego schematu GraphQL, podczas gdy eksplorator schematu w okienku po lewej stronie umożliwia nawigowanie, inspekcję i modyfikowanie obiektów uwidocznionych za pośrednictwem interfejsu API. Razem te narzędzia pomagają zrozumieć strukturę interfejsu API i kontrolować, jakie dane są dostępne dla klientów.

Kto używa widoku schematu

Widok schematu i eksplorator są przydatne w następujących celach:

• Inżynierowie danych konfigurują obiekty lakehouse i magazynu danych Fabric, aby były dostępne za pomocą GraphQL
• Deweloperzy aplikacji odnajdujący dostępne typy danych, pola i relacje sieci szkieletowej przed pisaniem zapytań
• Współautorzy obszaru roboczego platformy Fabric rozumieją i zarządzają strukturą dostępu do danych w swoim obszarze roboczym.
• Deweloperzy BI przeglądający relacje danych Fabric przy budowaniu niestandardowych aplikacji analitycznych

Użyj widoku schematu, aby eksplorować strukturę interfejsu API i eksplorator schematu, aby zmodyfikować, które obiekty danych są uwidocznione.

Uzyskiwanie dostępu do schematu i eksplorowanie go

Dostęp do widoku schematu można uzyskać z poziomu edytora zapytań lub bezpośrednio z poziomu elementu interfejsu API GraphQL. Aby otworzyć widok schematu, wybierz pozycję Schemat w lewym dolnym rogu. W widoku schematu jest wyświetlana tylko do odczytu, oparta na tekście wersja kompletnego języka SDL programu GraphQL ze wszystkimi wygenerowanymi typami, polami, zapytaniami i mutacjami.

Na poniższej ilustracji przedstawiono widok schematu z okienkiem Eksplorator schematu po lewej stronie:

Nawigowanie za pomocą eksploratora schematów

Eksplorator schematu w okienku po lewej stronie umożliwia nawigację i inspekcję wszystkich obiektów w interfejsie API. Eksplorator jest dostępny zarówno w widoku schematu, jak i w edytorze zapytań, co ułatwia eksplorowanie struktury interfejsu API podczas pisania zapytań.

Rozwiń węzły w Eksploratorze schematów, aby wyświetlić:

• Typy: typy GraphQL generowane na podstawie tabel i widoków źródła danych
• Zapytania: Automatycznie generowane operacje odczytu na potrzeby pobierania danych
• Mutacje: Automatycznie generowane operacje zapisu na potrzeby tworzenia, aktualizowania i usuwania danych (tylko magazyn)

Types

Typy reprezentują strukturę danych i pojawiają się pod nazwą źródła danych, z którego zostały wygenerowane. Na poniższej ilustracji przedstawiono typ SalesOrderDetail wygenerowany z tabeli SalesOrderDetail w punkcie końcowym analizy SQL AdventureWorks :

Queries

Interfejs API automatycznie generuje zapytania dotyczące pobierania danych z uwidacznianych obiektów. Rozwiń węzeł zapytania, aby wyświetlić wszystkie dostępne operacje odczytu:

Mutacje

Mutacje to operacje zapisu służące do tworzenia, aktualizowania i usuwania danych. Rozwiń węzeł mutacji, aby wyświetlić wszystkie dostępne operacje zapisu:

Uwaga

Mutacje są generowane tylko dla źródeł danych z Fabric Data Warehouse. Punkty końcowe usługi SQL Analytics (Lakehouses i dublowane bazy danych) są tylko do odczytu i obsługują tylko zapytania. Jeśli w Eksploratorze schematu nie widzisz operacji modyfikujących, sprawdź, czy masz połączenie z magazynem danych Fabric.

Modyfikowanie obiektów przy użyciu eksploratora schematów

Po wygenerowaniu początkowego schematu przez interfejs API możesz użyć Eksploratora schematów, aby uściślić dane uwidocznione za pośrednictwem interfejsu API. Eksplorator schematów udostępnia opcje zarządzania, które umożliwiają kontrolowanie struktury interfejsu API bez modyfikowania bazowych źródeł danych. Te narzędzia są niezbędne do obsługi czystego, dobrze zorganizowanego interfejsu API, który uwidacznia tylko potrzebne dane klientom.

Opcje modyfikacji dostępu

Aby zmodyfikować obiekt, wybierz wielokropek (...) obok dowolnego typu w Eksploratorze schematów. W poniższym przykładzie przedstawiono menu modyfikacji dla typu SalesOrderDetail :

Dostępne opcje modyfikacji

Aktualizowanie schematu — synchronizuje schemat graphQL z najnowszą strukturą ze źródła danych. Użyj tej funkcji, gdy dodano nowe tabele, widoki lub kolumny do źródła danych i chcesz je uwidocznić za pośrednictwem interfejsu API. Ta operacja odnajduje i dodaje nowe obiekty przy zachowaniu istniejącej konfiguracji.

Zmiana nazwy — zmienia sposób wyświetlania obiektu w interfejsie API GraphQL. Jest to przydatne w przypadku tworzenia bardziej intuicyjnych konwencji nazewnictwa interfejsów API lub ukrywania szczegółów implementacji od klientów. Na przykład możesz zmienić nazwę tbl_SalesOrderDetail na po prostu SalesOrderDetail. Zmiana nazwy dotyczy tylko schematu interfejsu API i nie modyfikuje bazowego obiektu źródła danych.

Usuń ze schematu — usuwa obiekt z interfejsu API GraphQL, dzięki czemu jest niedostępny dla klientów. Służy do ukrywania poufnych danych, usuwania przestarzałych obiektów lub upraszczania powierzchni interfejsu API. Dane pozostają w źródle danych; usunięto tylko ekspozycję API.

Zarządzanie relacjami — otwiera interfejs zarządzania relacjami, w którym można zdefiniować sposób łączenia się obiektów ze sobą. Relacje umożliwiają zagnieżdżone zapytania i przechodzenie grafu, co pozwala klientom pobierać powiązane dane w jednym żądaniu. Aby uzyskać więcej informacji, zobacz Zarządzanie relacjami w interfejsie API sieci szkieletowej dla języka GraphQL.

Właściwości — wyświetla szczegółowe metadane dotyczące obiektu, w tym oryginalną nazwę wyświetlaną w źródle danych, nazwę typu GraphQL, właściciela i lokalizację (nazwę obszaru roboczego i źródła danych). Użyj tej funkcji, aby sprawdzić, jak obiekty są mapowane między źródłem danych a interfejsem API GraphQL.

Włączanie i wyłączanie zapytań i mutacji

Funkcja włączania lub wyłączania zapytań i mutacji zapewnia administratorom i deweloperom szczegółową kontrolę nad dostępem i użyciem interfejsu API. Umożliwia selektywne aktywowanie lub dezaktywowanie określonych zapytań i mutacji w schemacie GraphQL. Umożliwia to dynamiczne zarządzanie możliwościami interfejsu API bez modyfikowania kodu lub wdrażania zmian.

Użyj tej funkcji w scenariuszach, takich jak:

• Wersjonowanie interfejsu API: wyłącz przestarzałe operacje podczas migracji klientów do nowych wersji
• Okna obsługi: tymczasowo wyłącz operacje zapisu (mutacje) podczas konserwacji danych
• Zabezpieczenia i zgodność: Ograniczanie dostępu do poufnych operacji bez usuwania ich ze schematu
• Etapowe wprowadzanie: włączanie nowych zapytań lub mutacji do testowania przed udostępnieniem ich szeroko

Zapytania i mutacje w eksploratorze schematów mają dwie inne opcje:

• Wyłącz: uniemożliwia uruchamianie zapytania lub mutacji wszystkich żądań. Jeśli próba wykonania zostanie podjęta, zostanie zwrócony błąd. Po wyłączeniu zapytania lub mutacji następuje ponowne ładowanie schematu, a zapytanie lub mutacja pojawiają się wyszarydzone w eksploratorze schematu.

• Włącz: umożliwia ponowne włączenie wcześniej wyłączonego zapytania lub mutacji. Kwerenda lub mutacja jest natychmiast dostępna po operacji ponownego ładowania schematu, która występuje po wybraniu opcji Włącz .

Uwaga

Zapytania i mutacje generowane automatycznie z procedur składowanych zachowują się inaczej niż te wygenerowane na podstawie tabel lub widoków. Można je usunąć tylko, a nie wyłączyć. Po usunięciu można je odczytać przy użyciu opcji Pobierz dane lub Aktualizuj schemat . Aby uzyskać więcej informacji, zobacz Procedury składowane.

Powiązana zawartość

• Interfejs API sieci szkieletowej dla edytora GraphQL
• Zarządzanie relacjami w Fabric API dla GraphQL
• Rozpocznij przygodę z Fabric API dla GraphQL