Host GraphQL endpoints in Data API builder (Host GraphQL endpoints in Data API builder)

Artykuł
07/10/2024

Jednostki skonfigurowane do udostępniania za pośrednictwem biblioteki GraphQL są dostępne w ścieżce domyślnej: https://{base_url}//graphql. Konstruktor interfejsu API danych automatycznie generuje schemat GraphQL z polami zapytań i mutacji dla wszystkich skonfigurowanych jednostek. Schemat GraphQL można eksplorować przy użyciu nowoczesnego klienta GraphQL, który zawiera funkcje, takie jak autouzupełnianie.

Jeśli wykonano przykład Wprowadzenie, w którym znajdują się books i jednostka authors skonfigurowana na potrzeby dostępu do języka GraphQL, możesz zobaczyć, jak łatwo jest używać języka GraphQL.

Format zestawu wyników

Zwrócony wynik jest obiektem JSON o tym formacie:

{
    "data": {}    
}

Nuta

Domyślnie zwracane są tylko pierwsze 100 elementów.

Obsługiwane typy główne

Konstruktor interfejsu API danych obsługuje następujące typy główne graphQL:

zapytania mutacje

Kwerendy

Każda jednostka ma obsługę następujących akcji:

stronicowania
Zapytanie według klucza podstawowego
zapytań ogólnych

Konstruktor interfejsu API danych, chyba że określono inaczej, używa pojedynczej nazwy jednostki za każdym razem, gdy zapytanie ma zwrócić pojedynczy element. Z drugiej strony konstruktor interfejsu API danych używa nazwy jednostki za każdym razem, gdy zapytanie ma zwrócić listę elementów. Na przykład jednostka book ma następujące elementy:

book_by_pk(): aby zwrócić zero lub jedną jednostkę
books(): aby zwrócić listę zero lub więcej jednostek

Paginacja

Wszystkie typy zapytań zwracające zero lub więcej elementów obsługują stronicowanie:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

obiekt item umożliwia dostęp do pól jednostek
hasNextPage jest ustawiona na wartość true, jeśli ma zostać zwróconych więcej elementów
endCursor zwraca nieprzezroczystym ciąg kursora, który może być używany z parametrami first i after zapytania w celu pobrania następnego zestawu (lub strony) elementów.

Zapytanie według klucza podstawowego

Każda jednostka obsługuje pobieranie określonego elementu za pośrednictwem klucza podstawowego przy użyciu następującego formatu zapytania:

<entity>_by_pk(<pk_colum>:<pk_value>)
{
    <fields>
}

Na przykład:

{
  book_by_pk(id:1010) {
    title
  }
}

Zapytanie ogólne

Każda jednostka obsługuje również ogólny wzorzec zapytania, dzięki czemu można poprosić o tylko żądane elementy w żądanej kolejności przy użyciu następujących parametrów:

filter: filtruje zwrócone elementy
orderBy: definiuje sposób sortowania zwracanych danych
first i after: zwraca tylko najważniejsze elementy n

Na przykład:

{
  authors(
    filter: {
        or: [
          { first_name: { eq: "Isaac" } }
          { last_name: { eq: "Asimov" } }
        ]
    }
  ) {
    items {
      first_name
      last_name
      books(orderBy: { year: ASC }) {
        items {
          title
          year
        }
      }
    }
  }
}

`filter`

Wartość parametru filter to wyrażenie predykatu (wyrażenie zwracające wartość logiczną) przy użyciu pól jednostki. W odpowiedzi są uwzględniane tylko elementy, w których wyrażenie daje wartość "True". Na przykład:

{
  books(filter: { title: { contains: "Foundation" } })
  {
    items {
      id
      title
      authors {
        items {
          first_name
          last_name
        }
      }
    }
  }
}

To zapytanie zwraca wszystkie książki ze słowem Foundation w tytule.

Operatory obsługiwane przez parametr filter to:

Operator	Typ	Opis	Przykład
`eq`	Porównanie	Równy	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Porównanie	Nie równa się	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Porównanie	Większe niż	`books(filter: { year: { gt: 1990 } })`
`gte`	Porównanie	Większe niż lub równe	`books(filter: { year: { gte: 1990 } })`
`lt`	Porównanie	Mniejsze niż	`books(filter: { year: { lt: 1990 } })`
`lte`	Porównanie	Mniejsze niż lub równe	`books(filter: { year: { lte: 1990 } })`
`isNull`	Porównanie	Ma wartość null	`books(filter: { year: { isNull: true} })`
`contains`	Struna	Contains	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Struna	Nie zawiera	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Struna	Rozpoczyna się od	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Struna	Koniec z	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Logiczny	Logiczne i	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Logiczny	Logiczne lub	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`orderBy`

Wartość orderby ustawić kolejność zwracanych elementów w zestawie wyników. Na przykład:

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

To zapytanie zwraca książki uporządkowane według title.

`first` i `after`

Parametr first ogranicza liczbę zwracanych elementów. Na przykład:

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

To zapytanie zwraca pierwsze pięć książek. Jeśli nie określono orderBy, elementy są uporządkowane na podstawie podstawowego klucza podstawowego. Wartość podana do orderBy musi być dodatnią liczbą całkowitą.

Jeśli w jednostce book znajduje się więcej elementów niż te jednostki żądane za pośrednictwem first, pole hasNextPage zwróci true, a endCursor zwróci ciąg, którego można użyć z parametrem after w celu uzyskania dostępu do następnych elementów. Na przykład:

query {
  books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

Mutacje

Dla każdej jednostki mutacje do obsługi operacji tworzenia, aktualizowania i usuwania są tworzone automatycznie. Operacja mutacji jest tworzona przy użyciu następującego wzorca nazwy: <operation><entity>. Na przykład w przypadku jednostki book mutacje będą następujące:

createbook: tworzenie nowej książki
updatebook: aktualizowanie istniejącej książki
deletebook: usuń określoną książkę

Tworzyć

Aby utworzyć nowy element żądanej jednostki, zapewnia się mutację create<entity>. Utworzona mutacja wymaga parametru item, w którym określono wartości dla obowiązkowych pól jednostki, które mają być używane podczas tworzenia nowego elementu.

create<entity>(item: <entity_fields>)
{
    <fields>
}

Na przykład:

mutation {
  createbook(item: {
    id: 2000,
    title: "Leviathan Wakes"    
  }) {
    id
    title
  }  
}

Aktualizacja

Aby zaktualizować element żądanej jednostki, zapewnia się mutację update<entity>. Mutacja aktualizacji wymaga dwóch parametrów:

<primary_key>, lista klucz-wartość kolumn klucza podstawowego i powiązane wartości identyfikujące element do zaktualizowania
item: parametr z obowiązkowymi wartościami pól jednostki do użycia podczas aktualizowania określonego elementu

update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

Na przykład:

mutation {
  updatebook(id: 2000, item: {
    year: 2011,
    pages: 577    
  }) {
    id
    title
    year
    pages
  }
}

Usunąć

Aby usunąć element żądanej jednostki, podano mutację delete<entity>. Kluczem podstawowym elementu do usunięcia jest wymagany parametr.

delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
    <fields>
}

Na przykład:

mutation {
  deletebook(id: 1234)
  {
    id
    title
  }  
}

Transakcje bazy danych dla mutacji

Aby przetworzyć typowe żądanie mutacji GraphQL, konstruktor interfejsu API danych tworzy dwa zapytania bazy danych. Jedno z zapytań bazy danych wykonuje akcję aktualizacji (lub) wstawiania (lub) usuwania, która jest skojarzona z mutacją. Inne zapytanie bazy danych pobiera dane żądane w zestawie wyboru.

Konstruktor interfejsu API danych wykonuje oba zapytania bazy danych w transakcji. Transakcje są tworzone tylko dla typów baz danych SQL.

W poniższej tabeli wymieniono poziomy izolacji, za pomocą których transakcje są tworzone dla każdego typu bazy danych.

Typ bazy danych	Poziom izolacji	Więcej informacji
Azure SQL (lub) SQL Server	Odczyt zatwierdzony	azure SQL
MySQL	Powtarzalny odczyt	MySQL
PostgreSQL	Odczyt zatwierdzony	PostgreSQL

dokumentacja konfiguracji GraphQL
interfejsu OpenAPI

Udostępnij za pośrednictwem

Host GraphQL endpoints in Data API builder (Host GraphQL endpoints in Data API builder)

Format zestawu wyników

Obsługiwane typy główne

Kwerendy

Zapytanie według klucza podstawowego

Zapytanie ogólne

`filter`

`orderBy`

`first` i `after`

Mutacje

Tworzyć

Aktualizacja

Usunąć

Transakcje bazy danych dla mutacji

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Host GraphQL endpoints in Data API builder (Host GraphQL endpoints in Data API builder)

Format zestawu wyników

Obsługiwane typy główne

Kwerendy

Paginacja

Zapytanie według klucza podstawowego

Zapytanie ogólne

filter

orderBy

first i after

Mutacje

Tworzyć

Aktualizacja

Usunąć

Transakcje bazy danych dla mutacji

Powiązana zawartość

Opinia

Dodatkowe zasoby

`filter`

`orderBy`

`first` i `after`