Udostępnij przez

API Fabric dla introspekcji GraphQL i eksportowania schematu

Podczas kompilowania aplikacji lub integrowania narzędzi zewnętrznych z interfejsem API usługi Fabric dla języka GraphQL należy zrozumieć strukturę interfejsu API — jakie typy są dostępne, jakie pola zawierają i jak odnoszą się do siebie nawzajem. Niezależnie od tego, czy generujesz kod klienta, tworzysz dokumentację, czy konfigurujesz narzędzia do zarządzania interfejsami API, uzyskiwanie dostępu do definicji schematu jest niezbędne.

API Fabric dla GraphQL udostępnia dwa uzupełniające mechanizmy pobierania informacji o schemacie: introspekcję dla programowych zapytań uruchomieniowych i eksport schematu do uzyskania kompletnego pliku schematu. Obie metody zapewniają dostęp do tego samego bazowego schematu, ale każda z nich obsługuje różne przepływy pracy i przypadki użycia.

Wskazówka

Chcesz zobaczyć introspekcję w działaniu? Wypróbuj samouczek Łączenie agentów AI z Fabric API dla GraphQL przy użyciu lokalnego serwera Model Context Protocol (MCP). W tym przewodniku praktycznym pokazano, jak agenci sztucznej inteligencji używają introspekcji do automatycznego odkrywania i tworzenia zapytań dotyczących danych Fabric przy użyciu języka naturalnego.

Kto używa introspekcji i eksportu schematu

Introspekcja i eksport schematu są cenne dla:

  • Deweloperzy aplikacji tworzący klientów korzystających z danych sieci Szkieletowej i muszą generować kod bezpieczny dla typu
  • Kontrybutorzy obszaru roboczego Fabric rozumieją dostępne struktury danych oraz testują dostęp do danych
  • Narzędzia programistyczne i IDE zapewniające autouzupełnianie i funkcję IntelliSense dla interfejsów API GraphQL Fabric
  • Integracje usługi Azure API Management, które kierują i zabezpieczają ruch związany z usługą Fabric GraphQL na poziomie przedsiębiorstwa
  • Administratorzy sieci szkieletowej przeprowadzają inspekcję uwidocznionych struktur danych i weryfikowanie kontroli dostępu
  • Agenci i asystenci sztucznej inteligencji używający protokołu MCP (Model Context Protocol) do odnajdywania i przeprowadzania zapytań dotyczących danych Fabric w naturalny sposób
  • Deweloperzy Power Platform powinni zrozumieć schematy danych Fabric przed przystąpieniem do tworzenia integracji
  • Pipeline CI/CD śledzące wersje schematów GraphQL dla usługi Fabric i weryfikujące zgodność wersji w różnych środowiskach

Wybierz introspekcję, gdy konieczne jest programowe wykonywanie zapytań dotyczących informacji o schemacie w trakcie działania, na przykład w celu zasilenia narzędzi programistycznych, uruchomienia agentów sztucznej inteligencji lub implementacji dynamicznych funkcji klienta. Wybierz eksport schematu , gdy potrzebujesz kompletnego pliku schematu do użycia w trybie offline, kontroli wersji, integracji bramy interfejsu API lub udostępniania z zespołami zewnętrznymi.

  • Introspection: Programowe wykonywanie zapytań względem schematu przy użyciu systemu introspekcji GraphQL, który jest częścią standardu GraphQL. Zapytania introspekcji umożliwiają dynamiczne odkrywanie typów, pól i relacji, a także wspierają działanie wielu narzędzi programistycznych GraphQL.

  • Eksportowanie schematu: pobierz kompletny plik SDL (GraphQL Schema Definition Language), który zawiera całą definicję schematu do użytku w trybie offline, udostępniania lub integracji narzędzi.

Introspekcja

Domyślnie introspekcja jest wyłączona w interfejsie API dla elementów GraphQL. To ustawienie może być przełączane tylko przez administratorów obszaru roboczego. Wszyscy inni użytkownicy zobaczą nieaktywny suwak.

Aby włączyć introspekcję:

  1. Wybierz ikonę koła zębatego Ustawienia interfejsu API w górnym menu.

    Zrzut ekranu pokazujący pasek portalu z przyciskiem koła zębatego do ustawień.

  2. W obszarze nawigacji po lewej stronie wybierz stronę Introspection .

    Zrzut ekranu przedstawiający suwak ustawienia introspekcji.

  3. Wybierz przełącznik, aby włączyć introspekcję. Włączenie introspekcji ujawnia informacje o schemacie wszystkim użytkownikom mającym dostęp do punktu końcowego API.

  4. Pojawia się okno dialogowe potwierdzenia. Wybierz pozycję Potwierdź , aby włączyć introspekcję lub Anuluj , aby pozostawić ją wyłączoną.

    Zrzut ekranu przedstawiający okno dialogowe potwierdzenia włączania introspekcji.

Przykład zapytania introspekcji

Oto szybki przykład zapytania introspekcji w celu pobrania dostępnych typów ze schematu:

  1. Utwórz nowe zapytanie w edytorze GraphQL. Wybierz ikonę znaku plus + obok istniejących kart, aby otworzyć nową kartę zapytania.

    Zrzut ekranu przedstawiający przycisk nowego zapytania w edytorze GraphQL.

  2. Wprowadź następujące zapytanie introspekcji w edytorze:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Wybierz przycisk Uruchom , aby wykonać zapytanie.

  4. W okienku wyników zostanie wyświetlona lista wszystkich typów zdefiniowanych w schemacie.

    Zrzut ekranu przedstawiający przykład zapytania introspekcji.

Zapytania introspekcji mogą zwracać duże ilości informacji. Zakres zapytań można zawęzić, będąc bardziej szczegółowymi w żądaniu introspekcji. Na przykład zamiast wykonywać zapytania dotyczące wszystkich typów, możesz wykonać zapytanie dotyczące określonego typu:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Uruchomienie zapytania zwraca szczegółowe informacje o typie ProductCategory :

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Typowe wzorce filtrowania podczas przetwarzania wyników introspekcji obejmują:

  • Wykluczanie typów rozpoczynających się od podwójnych podkreśleń (__), które są typami systemu GraphQL
  • Dołączanie typów rozpoczynających się od określonych prefiksów, takich jak ProductCategory

W tych przykładach pokazano standardową składnię introspekcji GraphQL, która działa we wszystkich implementacjach języka GraphQL. To omówienie obejmuje podstawowe wzorce introspekcji — aby uzyskać szczegółowe informacje na temat systemu introspekcji, zaawansowanych technik zapytań i dodatkowych możliwości, zobacz oficjalną dokumentację programu GraphQL Foundation dotyczącą introspekcji.

Eksportowanie schematu

Gdy potrzebujesz pełnej kopii definicji schematu w trybie offline, użyj funkcji eksportowania schematu bezpośrednio z portalu sieci szkieletowej. Otwórz interfejs API dla języka GraphQL i wybierz pozycję Eksportuj schemat na pasku narzędzi. Przeglądarka pobiera plik SDL (Schema Definition Language) zawierający kompletną definicję schematu.

Zrzut ekranu przedstawiający przycisk eksportu schematu.

Opis pliku SDL

Wyeksportowany plik używa języka definicji schematu programu GraphQL (SDL), formatu czytelnego dla człowieka, który definiuje typy, pola i relacje interfejsu API. Plik SDL zawiera następujące elementy:

  • Typy obiektów reprezentujące jednostki danych z ich polami
  • Operacje zapytań definiujące sposób pobierania danych
  • Operacje mutacji na potrzeby tworzenia, aktualizowania lub usuwania danych
  • Argumenty pól określające parametry wejściowe i ich typy
  • Opisy typów zawierające dokumentację dla każdego elementu

Plik SDL można otworzyć w dowolnym edytorze tekstów, aby przejrzeć strukturę schematu. Jest to szczególnie przydatne do zrozumienia kompletnej powierzchni interfejsu API przed zintegrowaniem jej z aplikacjami.

Korzystanie z wyeksportowanego schematu

Typowe przypadki użycia wyeksportowanego pliku SDL obejmują:

  • Integracja bramy API: import do Azure API Management w celu dodania uwierzytelniania, limitowania przepustowości i buforowania
  • Konfiguracja środowiska deweloperskiego: konfigurowanie funkcji IntelliSense w programie Visual Studio Code pod kątem autouzupełniania i walidacji
  • Kontrola wersji: zatwierdzanie w usłudze Git lub innych systemach kontroli źródła w celu śledzenia ewolucji schematu w czasie
  • Współpraca zespołowa: udostępnianie partnerom zewnętrznym lub zespołom deweloperów, którzy muszą zrozumieć strukturę interfejsu API
  • Generowanie kodu: używanie z generatorami kodu GraphQL do tworzenia klientów bezpiecznych pod względem typów w językach TypeScript, C#, Java lub innych językach
  • Dokumentacja: generowanie dokumentacji referencyjnej interfejsu API przy użyciu narzędzi takich jak GraphQL Voyager lub GraphQL Markdown

W przeciwieństwie do zapytań introspekcji eksport schematu nie wymaga włączenia introspekcji i działa niezależnie od ustawień introspekcji interfejsu API. Dzięki temu jest to niezawodny sposób uzyskiwania dostępu do definicji schematu w celach administracyjnych i programistycznych.

Zarządzanie zmianami schematu

Schematy graphQL mogą ewoluować wraz z upływem czasu podczas dodawania nowych typów, pól lub możliwości do interfejsu API. Gdy schemat ulegnie zmianie, wyeksportowane pliki SDL staną się nieaktualne. Rozważ następujące rozwiązania:

  • Ponowne eksportowanie po zmianach: Pobierz nowy plik SDL za każdym razem, gdy zmodyfikujesz schemat interfejsu API w Fabric. Zmiany schematu obejmują dodawanie źródeł danych, modyfikowanie uwidocznionych typów lub aktualizowanie definicji pól.
  • Kontrola wersji: zatwierdź każdy wyeksportowany schemat do systemu kontroli źródła za pomocą opisowych komunikatów zatwierdzenia. Spowoduje to utworzenie dziennika inspekcji ewolucji schematu i umożliwi wycofywanie w razie potrzeby.
  • Komunikacja: jeśli zewnętrzne zespoły lub aplikacje zależą od schematu, powiadom ich o znaczących zmianach. Chociaż język GraphQL obsługuje zmiany addytywne bez przerywania istniejących zapytań, usuwanie lub zmienianie nazw pól może mieć wpływ na klientów.
  • Automatyzacja: W przypadku potoków CI/CD rozważ automatyzację eksportu schematów w ramach procesu wdrażania, aby zapewnić synchronizację dokumentacji i narzędzi z API.

Osoba odpowiedzialna za modyfikowanie schematu interfejsu API (zazwyczaj inżynier danych lub deweloper interfejsu API) powinna wyeksportować i wersjonować zaktualizowany schemat, aby zachować spójność między Fabric API a systemami zewnętrznymi, które od niego zależą.

Treści powiązane

  • Last updated on