wtyczka gql_request

Wtyczka gql_request uruchamia zapytanie języka GQL (ISO Graph Query Language) względem grafu w Microsoft Fabric i zwraca wyniki jako tabelę. Przetwórz zwracaną tabelę za pomocą standardowych operatorów języka Kusto Query Language (KQL). Wywołaj wtyczkę za pomocą operatora evaluate.

Wtyczka używa interfejsu API zapytań GQL Microsoft Fabric. Opcjonalnie można zadeklarować oczekiwany schemat danych wyjściowych. Zapewnienie, że pozwala uniknąć dodatkowego zapytania GQL podczas odnajdywania schematu.

Note

Ta wtyczka używa języka zapytań graph (GQL) do wykonywania zapytań Fabric grafów, a nie graphQL, języka zapytań interfejsu API.

Note

Wtyczka gql_request jest dostępna w wersji zapoznawczej.

Prerequisites

  • Wykres Microsoft Fabric zawierający dane. Aby utworzyć i załadować przykładowy graf, zobacz Przewodnik Szybki start dla programu Graph.
  • Uprawnienie do wykonywania zapytań względem grafu w obszarze roboczym Fabric.
  • Zasady objaśnień klastra muszą zezwalać Fabric wywołania żądań GQL programu Graph na api.fabric.microsoft.com. Aby zmienić te zasady, potrzebujesz AllDatabasesAdmin uprawnień lub Ops uprawnień.

Syntax

evaluate gql_request ( ConnectionString,GqlQuery) [:OutputSchema]

Dowiedz się więcej na temat konwencji składni w dokumentacji dotyczącej składni.

Parameters

Name Typ Wymagane Description
ConnectionString (Parametr połączenia) string Yes Adres URL modelu grafu Fabric, po którym następuje ;Impersonate. Aby uzyskać obsługiwany format, zobacz Parametry połączenia.
GqlQuery string Yes Zapytanie GQL do uruchomienia względem grafu.
OutputSchema - - Nazwy i typy oczekiwanych kolumn wyjściowych. Użyj składni (ColumnName:ColumnType [, ...]).

Note

Określanie parametru OutputSchema jest zalecane szczególnie wtedy, gdy zapytanie GQL może nie zwracać żadnych wierszy. Umożliwia to usłudze Kusto określenie kolumn wyjściowych i typów wtyczki bez uruchamiania zapytania podczas odnajdywania schematu. Wtyczka zwraca błąd, jeśli zwrócony schemat jest niezgodny ze zadeklarowanym schematem.

Parametry połączenia

Określ adres URL modelu grafów Fabric, po którym następuje ;Impersonate dyrektywa uwierzytelniania:

https://api.fabric.microsoft.com/v1/workspaces/<WorkspaceId>/GraphModels/<GraphModelId>;Impersonate

WorkspaceId muszą GraphModelId być prawidłowymi identyfikatorami GUID.

Uwierzytelnianie i autoryzacja

Wtyczka używa Microsoft Entra uwierzytelniania w imieniu. Aparat uzyskuje token dla żądanego użytkownika i wysyła zapytanie do grafu w kontekście zabezpieczeń tego użytkownika. Użytkownik musi mieć uprawnienia na grafie.

Użyj ;Impersonate jako dyrektywy uwierzytelniania. Tożsamość zarządzana, jednostka usługi i uwierzytelnianie klucza aplikacji nie są obsługiwane.

Important

Użyj zaciemnionego literału ciągu dla dowolnego ciągu zawierającego poufne informacje. Zaciemnione wartości nie są wyświetlane w śledzeniu kusto.

Konfigurowanie zasad objaśnienie

Wtyczka wykonuje zewnętrzne wywołanie do Microsoft Fabric. Ponieważ domyślne zasady objaśnień blokują Fabric objaśnień żądań GQL programu Graph, administrator klastra musi jawnie zezwolić na punkt końcowy Fabric.

Następujące polecenie scala restrykcyjną regułę żądania GQL programu Graph Fabric z istniejącymi zasadami objaśnień klastra:

.alter-merge cluster policy callout @'[{
    "CalloutType": "gql", 
    "CalloutUriRegex": "api\\.fabric\\.microsoft\\.com/.*", 
    "CanCall": true
}]'

Sprawdź zasady:

.show cluster policy callout

Returns

Wtyczka zwraca wynik zapytania GQL jako tabelę KQL. Jeśli określisz wartość OutputSchema, zwrócone kolumny muszą być zgodne ze zadeklarowanym schematem. W przypadku przewidywalnych wyników projektuj właściwości potrzebne w zapytaniu GQL zamiast zwracać całe węzły, krawędzie lub ścieżki.

Examples

Zwracanie wierszy z grafu

W tym przykładzie przyjęto założenie, że wykres zawiera Person węzły z właściwościami firstName i lastName . Zwraca maksymalnie 100 nazw.

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/graphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)
    RETURN p.firstName AS firstName, p.lastName AS lastName
    LIMIT 100')
  : (firstName:string, lastName:string)

Przetwarzanie wyników GQL za pomocą usługi Kusto

Poniższy przykład zlicza węzły Person z relacją LIVES_IN z poszczególnymi Cityelementami , a następnie używa języka KQL do wyświetlania miast z ponad 10 osobami uporządkowanymi według liczby. Przyjęto założenie, że graf zawiera Person węzły połączone relacjamiLIVES_IN.City

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/GraphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)-[:LIVES_IN]->(c:City)
    RETURN c.name AS city, count(DISTINCT p) AS PersonCount')
  : (city:string, PersonCount:long)
| where PersonCount > 10
| order by PersonCount desc

To zlicza różne osoby na nazwę miasta; miasta dzielące się nazwą są grupowane razem.

Wskazówka

Filtruj, projektuj i ogranicz dane w GQL, gdy jest to możliwe, aby zmniejszyć ilość danych zwracanych do usługi Kusto.

Troubleshooting

Wtyczka odróżnia błędy transportu od błędów aplikacji GQL. Błąd aplikacji GQL może pojawić się w odpowiedzi HTTP 200. Wtyczka ocenia stan odpowiedzi, zawiera dostępne kody stanu, opisy i zagnieżdżone przyczyny oraz zwraca błąd jako błąd zapytania.

W poniższej tabeli wymieniono typowe błędy zwracane przez wtyczkę oraz ich możliwe przyczyny i rozwiązania.

Error Przyczyna i rozwiązanie
Nieprawidłowa parametry połączenia Upewnij się, że parametry połączenia jest zgodny z obsługiwanym formatem, identyfikatory obszarów roboczych i identyfikatorów modelu grafu są prawidłowymi identyfikatorami GUID, a ciąg kończy się ciągiem ;Impersonate. Nie dołączaj /executeQuery parametrów zapytania ani fragmentu w adresie URL. Wtyczka tworzy punkt końcowy interfejsu API wewnętrznie.
Niezgodność schematu wyjściowego Upewnij się, że zadeklarowane nazwy kolumn i typy KQL są zgodne z kolumnami i typami wyników GQL.
Nieobsługiwany typ wyniku GQL Project poszczególnych właściwości skalarnych w zapytaniu GQL. W przypadku wartości złożonych rozważ użycie biblioteki GQL TO_JSON_STRING w celu zwrócenia reprezentacji ciągu.
Objaśnienie nie jest dozwolone Skonfiguruj zasady objaśnienie klastra, aby zezwolić na wywołania żądań GQL programu Fabric Graph do usługi api.fabric.microsoft.com.
Błąd uwierzytelniania lub autoryzacji Upewnij się, że tożsamość obiektu wywołującego może uzyskać dostęp do obszaru roboczego i grafu.
Błąd żądania HTTP Sprawdź dostępność usługi Microsoft Fabric, dostępność punktu końcowego i odpowiedzi ograniczania przepustowości.
Błąd zapytania GQL Przejrzyj szczegóły błędu zapytania, w tym opis stanu GQL, diagnostykę i zagnieżdżone przyczyny, jeśli są dostępne.

Treści powiązane

  • Ostatnia aktualizacja o