Konfigurowanie narzędzia rozpoznawania języka GraphQL

Artykuł
05/02/2024

DOTYCZY: Wszystkie warstwy usługi API Management

Skonfiguruj program rozpoznawania w celu pobierania lub ustawiania danych dla pola GraphQL w typie obiektu określonym w schemacie GraphQL. Schemat należy zaimportować do usługi API Management jako interfejs API GraphQL.

Obecnie usługa API Management obsługuje programy rozpoznawania, które mogą uzyskiwać dostęp do następujących źródeł danych:

Źródło danych oparte na protokole HTTP (interfejs API REST lub SOAP)
Baza danych usługi Cosmos DB
Azure SQL database

Fakty, które trzeba znać

Rozpoznawanie nazw to zasób zawierający definicję zasad wywoływaną tylko wtedy, gdy jest wykonywany pasujący typ obiektu i pole w schemacie.
Każdy program rozpoznawania nazw rozpoznaje dane dla jednego pola. Aby rozwiązać problemy z danymi dla wielu pól, skonfiguruj oddzielny moduł rozpoznawania dla każdego z nich.
Zasady dotyczące zakresu rozpoznawania są oceniane po każdym inbound wystąpieniu zasad i backend w potoku wykonywania zasad. Nie dziedziczą one zasad z innych zakresów. Aby uzyskać więcej informacji, zobacz Zasady w usłudze API Management.
Zasady o zakresie interfejsu API można skonfigurować dla interfejsu API GraphQL niezależnie od zasad o zakresie rozpoznawania nazw. Na przykład dodaj zasady validate-graphql-request do zakresu, aby zweryfikować inbound żądanie przed wywołaniem narzędzia rozpoznawania. Konfigurowanie zasad o zakresie interfejsu API na karcie Zasady interfejsu API dla interfejsu API.
Aby obsługiwać interfejs i typy unii w programach rozpoznawania graphQL, odpowiedź zaplecza musi już zawierać __typename pole lub zmienić przy użyciu zasad zestawu treści , aby uwzględnić __typenameelement .

Wymagania wstępne

Istniejące wystąpienie usługi API Management. Utwórz go, jeśli jeszcze tego nie zrobiono.
Zaimportuj przekazywanie lub syntetyczny interfejs API GraphQL.

Tworzenie narzędzia rozpoznawania nazw

Poniższe kroki umożliwiają utworzenie narzędzia rozpoznawania przy użyciu źródła danych opartego na protokole HTTP. Ogólne kroki są podobne dla każdego narzędzia rozpoznawania problemów, który używa obsługiwanego źródła danych.

W witrynie Azure Portal przejdź do wystąpienia usługi API Management.
W menu po lewej stronie wybierz pozycję Interfejsy API, a następnie nazwę interfejsu API GraphQL.
Na karcie Schemat przejrzyj schemat pola w typie obiektu, w którym chcesz skonfigurować program rozpoznawania nazw.
1. Wybierz pole, a następnie na lewym marginesie umieść wskaźnik myszy.
2. Wybierz pozycję + Dodaj program rozpoznawania.
Na stronie Tworzenie narzędzia rozpoznawania nazw :
1. Zaktualizuj właściwość Nazwa, jeśli chcesz, opcjonalnie wprowadź opis i potwierdź lub zaktualizuj opcje Typ i Pole.
2. Wybierz źródło danych programu resolver. W tym przykładzie wybierz pozycję Interfejs API HTTP.
W edytorze zasad rozpoznawania nazw zaktualizuj http-data-source zasady za pomocą elementów podrzędnych dla danego scenariusza.
1. Zaktualizuj wymagany http-request element przy użyciu zasad, aby przekształcić operację GraphQL na żądanie HTTP.
2. Opcjonalnie dodaj http-response element i dodaj zasady podrzędne, aby przekształcić odpowiedź HTTP programu resolver. http-response Jeśli element nie zostanie określony, odpowiedź zostanie zwrócona jako nieprzetworzony ciąg.
3. Wybierz pozycję Utwórz.
Program rozpoznawania jest dołączany do pola i pojawia się na karcie Narzędzia rozpoznawania nazw.

Zarządzanie usługami rozpoznawania nazw

Wyświetlanie listy narzędzi rozpoznawania nazw dla interfejsu API graphQL i zarządzanie nimi na karcie Narzędzia rozpoznawania interfejsu API.

Na karcie Narzędzia rozpoznawania nazw:

Kolumna Połączona wskazuje, czy program rozpoznawania nazw jest skonfigurowany dla pola, które znajduje się obecnie w schemacie GraphQL. Jeśli program rozpoznawania nie jest połączony, nie można go wywołać.
W menu kontekstowym (...) dla narzędzia rozpoznawania nazw znajdź polecenia klonowania, edycji lub usuwania narzędzia rozpoznawania. Sklonuj wymieniony program rozpoznawania, aby szybko utworzyć podobny program rozpoznawania, który jest przeznaczony dla innego typu i pola.
Możesz utworzyć nowy program rozpoznawania nazw, wybierając pozycję + Utwórz.

Edytowanie i testowanie narzędzia rozpoznawania

Podczas edytowania pojedynczego modułu rozpoznawania zostanie otwarta strona Edytowanie narzędzia rozpoznawania. Masz następujące możliwości:

Zaktualizuj zasady rozpoznawania nazw i opcjonalnie źródło danych. Zmiana źródła danych zastępuje bieżące zasady rozpoznawania nazw.
Zmień typ i pole docelowe programu rozpoznawania.
Przetestuj i debuguj konfigurację narzędzia rozpoznawania. Podczas edytowania zasad rozpoznawania nazw wybierz pozycję Uruchom test , aby sprawdzić dane wyjściowe ze źródła danych, które można zweryfikować względem schematu. Jeśli wystąpią błędy, odpowiedź zawiera informacje dotyczące rozwiązywania problemów.

Kontekst graphQL

Kontekst żądania i odpowiedzi modułu rozpoznawania nazw (jeśli określono) różni się od kontekstu oryginalnego żądania interfejsu API bramy:
- context.GraphQL właściwości są ustawiane na argumenty (Arguments) i obiekt nadrzędny (Parent) dla bieżącego wykonywania rozpoznawania.
- Kontekst żądania zawiera argumenty przekazywane w zapytaniu GraphQL jako jego treści.
- Kontekst odpowiedzi to odpowiedź z niezależnego wywołania wykonanego przez program rozpoznawania nazw, a nie kontekstu pełnej odpowiedzi dla żądania bramy. Zmienna context przekazywana przez potok żądania i odpowiedzi jest rozszerzona o kontekst GraphQL, gdy jest używany z narzędziem rozpoznawania graphQL.

Kontekście. GraphQL.parent

Parametr context.GraphQL.parent jest ustawiony na obiekt nadrzędny dla bieżącego wykonywania rozpoznawania. Rozważmy następujący schemat częściowy:

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

Rozważ również zapytanie GraphQL dla wszystkich informacji dotyczących określonego bloga:

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Jeśli ustawisz program rozpoznawania nazw dla comments pola w typie Blog , musisz zrozumieć, którego identyfikatora blogu użyć. Identyfikator bloga można uzyskać, jak context.GraphQL.Parent["id"] pokazano w poniższym narzędziu rozpoznawania:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

Kontekście. GraphQL.Arguments

Argumenty sparametryzowanego zapytania GraphQL są dodawane do elementu context.GraphQL.Arguments. Rozważmy na przykład następujące dwa zapytania:

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

Te zapytania to dwa sposoby wywoływania narzędzia rozpoznawania getComment nazw. Narzędzie GraphQL wysyła następujący ładunek JSON:

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

Program rozpoznawania można zdefiniować w następujący sposób:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

Następne kroki

Aby uzyskać więcej przykładów rozpoznawania problemów, zobacz:

Share via