Konfigurowanie narzędzia rozpoznawania języka GraphQL

2025-04-10

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.

Uwaga

Obecnie ta funkcja nie jest dostępna w obszarach roboczych.

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ć

Resolver to zasób zawierający definicję polityki, która jest wywoływana tylko wtedy, gdy wykonywany jest 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 wszelkich zasadach inbound 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.
Można skonfigurować polityki związane z zakresem API dla GraphQL niezależnie od polityk związanych z zakresem resolverów. Na przykład dodaj politykę validate-graphql-request do zakresu, aby zweryfikować inbound żądanie przed wywołaniem resolvera. Skonfiguruj polisy o zasięgu API na karcie Polisy API dla interfejsu API.
Aby obsługiwać typy interfejsów i unii w resolverach GraphQL, odpowiedź z backendu musi już zawierać pole __typename, albo być zmieniona za pomocą polityki set-body, aby uwzględniała element __typename.

Wymagania wstępne

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

Utwórz resolver

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 + Dodaj resolver.
Na stronie Kreator Resolvera:
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ę API HTTP.
W edytorze polityki Resolver zaktualizuj http-data-source politykę, dodając elementy podrzędne odpowiednie dla twojego 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.
Resolver jest dołączany do pola i pojawia się na karcie Rozwiązania.

Zarządzanie resolverami

Zarządzaj rozwiązywaczami dla interfejsu API GraphQL na karcie Rozwiązywacze interfejsu API.

Na karcie Resolvers:

Kolumna Połączona wskazuje, czy resolver 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 resolvera znajdź polecenia Klonowania, Edycji lub Usuwania resolvera. 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 politykę resolvera 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 resolvera (jeśli określono) różni się od kontekstu oryginalnego żądania API bramy.
- context.GraphQL właściwości są ustawiane na argumenty (Arguments) i obiekt nadrzędny (Parent) w trakcie bieżącego wykonywania rozpoznawania.
- Kontekst żądania zawiera argumenty przekazywane w zapytaniu GraphQL jako jego treść.
- 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 uzupełniona kontekstem GraphQL, gdy jest używana z resolverem GraphQL.

kontekst.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 resolver dla pola comments w typie Blog, warto zrozumieć, którego identyfikatora bloga użyć. Identyfikator bloga można uzyskać, używając context.GraphQL.Parent["id"] jak pokazano w poniższym resolverze:

<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>

kontekst.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 getComment resolvera. 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>

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

Udostępnij za pośrednictwem