Aracılığıyla paylaş

Veri API'si oluşturucusunda GraphQL uç noktalarını barındırma

  • Makale

GraphQL aracılığıyla kullanılabilir olacak şekilde yapılandırılan varlıklar, varsayılan yolda kullanılabilir: https://{base_url}//graphql. Veri API oluşturucusu, yapılandırılmış tüm varlıklar için sorgu ve mutasyon alanları içeren bir GraphQL şemasını otomatik olarak oluşturur. GraphQL şeması, otomatik tamamlama gibi özellikler içeren modern bir GraphQL istemcisi kullanılarak incelenebilir.

GraphQL erişimi için yapılandırılmış books ve authors varlığının bulunduğu Başlarken örneğini izlediyseniz GraphQL'i kullanmanın ne kadar kolay olduğunu görebilirsiniz.

Sonuç kümesi biçimi

Döndürülen sonuç şu biçime sahip bir JSON nesnesidir:

{
    "data": {}    
}

Not

Varsayılan olarak yalnızca ilk 100 öğe döndürülür.

Desteklenen kök türleri

Veri API'sinin oluşturucusu aşağıdaki GraphQL kök türlerini destekler:

SorgularMutasyonlar

Sorgu

Her varlığın aşağıdaki eylemler için desteği vardır:

  • sayfalandırma
  • Birincil anahtara göre sorgu
  • Genel Sorgu

Aksi belirtilmediği sürece veri API oluşturucusu, sorgunun tek bir öğe döndürmesi beklendiğinde varlığın tek adını kullanır. Buna karşılık Veri API'si oluşturucusu, sorgunun öğe listesi döndürmesi beklendiğinde varlığın çoğul adını kullanır. Örneğin, book varlığında aşağıdakiler vardır:

  • book_by_pk(): sıfır veya bir varlık döndürmek için
  • books(): sıfır veya daha fazla varlığın listesini döndürmek için

Sayfalandırma

Sıfır veya daha fazla öğe döndüren tüm sorgu türleri sayfalandırmayı destekler:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}
  • item nesnesi varlık alanlarına erişime izin verir
  • döndürülecek daha fazla öğe varsa hasNextPage true olarak ayarlanır
  • endCursor, sonraki öğe kümesini (veya sayfasını) almak için first ve after sorgu parametreleriyle kullanılabilen opak bir imleç dizesi döndürür.

Birincil anahtara göre sorgulama

Her varlık, aşağıdaki sorgu biçimini kullanarak birincil anahtarı aracılığıyla belirli bir öğenin alınmasını destekler:

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

Mesela:

{
  book_by_pk(id:1010) {
    title
  }
}

Genel sorgu

Her varlık, aşağıdaki parametreleri kullanarak yalnızca istediğiniz öğeleri istediğiniz sırayla isteyebileceğiniz genel bir sorgu desenini de destekler:

  • filter: döndürülen öğeleri filtreler
  • orderBy: Döndürülen verilerin nasıl sıralanacağını tanımlar
  • first ve after: yalnızca en üstteki n öğelerini döndürür

Mesela:

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

filter

filter parametresinin değeri, varlığın alanlarını kullanan koşul ifadesidir (boole değeri döndüren bir ifade). Yalnızca ifadenin 'True' olarak değerlendirildiği öğeler yanıta eklenir. Mesela:

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

Bu sorgu, başlıkta Foundation sözcüğü bulunan tüm kitapları döndürür.

filter parametresi tarafından desteklenen işleçler şunlardır:

Operatör Tür Tarif Örnek
eq Karşılaştırma Eşit books(filter: { title: { eq: "Foundation" } })
neq Karşılaştırma Eşit değil books(filter: { title: { neq: "Foundation" } })
gt Karşılaştırma Büyüktür books(filter: { year: { gt: 1990 } })
gte Karşılaştırma Büyüktür veya eşittir books(filter: { year: { gte: 1990 } })
lt Karşılaştırma Küçüktür books(filter: { year: { lt: 1990 } })
lte Karşılaştırma Küçük veya eşit books(filter: { year: { lte: 1990 } })
isNull Karşılaştırma Null books(filter: { year: { isNull: true} })
contains Dizgi Içerir books(filter: { title: { contains: "Foundation" } })
notContains Dizgi İçermez books(filter: { title: { notContains: "Foundation" } })
startsWith Dizgi Şununla başlar: books(filter: { title: { startsWith: "Foundation" } })
endsWith Dizgi Bitiş: books(filter: { title: { endsWith: "Empire" } })
and Mantıklı Mantıksal ve authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })
or Mantıklı Mantıksal veya authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })

orderBy

orderby değeri, sonuç kümesindeki öğelerin döndürüldiği sırayı ayarlar. Mesela:

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

Bu sorgu, titletarafından sıralanmış kitapları döndürür.

first ve after

parametresi first döndürülen öğe sayısını sınırlar. Mesela:

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

Bu sorgu ilk beş kitabı döndürür. hiçbir orderBy belirtilmediğinde, öğeler temel alınan birincil anahtara göre sıralanır. orderBy için sağlanan değer pozitif bir tamsayı olmalıdır.

book varlığında firstaracılığıyla istenen varlıklardan daha fazla öğe varsa, hasNextPage alanı trueolarak değerlendirilir ve endCursor sonraki öğelere erişmek için after parametresiyle kullanılabilecek bir dize döndürür. Mesela:

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

Mutasyon

Her varlık için oluşturma, güncelleştirme ve silme işlemlerini destekleyen mutasyonlar otomatik olarak oluşturulur. Mutasyon işlemi şu ad deseni kullanılarak oluşturulur: <operation><entity>. Örneğin, book varlığı için mutasyonlar şöyle olacaktır:

  • createbook: yeni bir kitap oluşturma
  • updatebook: Mevcut bir kitabı güncelleştirme
  • deletebook: Belirtilen kitabı sil

Yaratmak

İstenen varlığın yeni bir öğesini oluşturmak için create<entity> mutasyonu sağlanır. Oluşturulan mutasyon, varlığın zorunlu alanlarının değerlerinin yeni öğe oluşturulurken kullanılması için belirtilen item parametresini gerektirir.

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

Mesela:

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

Güncelleştirmek

İstenen varlığın bir öğesini güncelleştirmek için update<entity> mutasyonu sağlanır. Güncelleştirme mutasyonu iki parametre gerektirir:

  • <primary_key>, güncelleştirilecek öğeyi tanımlamak için birincil anahtar sütunlarının ve ilgili değerlerin anahtar-değer listesi
  • item: belirtilen öğe güncelleştirilirken kullanılacak varlığın zorunlu alan değerlerine sahip parametre
update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

Mesela:

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

Silmek

İstenen varlığın bir öğesini silmek için delete<entity> mutasyonu sağlanır. Silinecek öğenin birincil anahtarı gerekli parametredir.

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

Mesela:

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

Mutasyon için veritabanı işlemleri

Tipik bir GraphQL mutasyon isteğini işlemek için Veri API'si oluşturucusu iki veritabanı sorgusu oluşturur. Veritabanı sorgularından biri mutasyonla ilişkili güncelleştirme (veya) ekleme (veya) silme eylemini gerçekleştirir. Diğer veritabanı sorgusu, seçim kümesinde istenen verileri getirir.

Veri API'si oluşturucusu bir işlemde her iki veritabanı sorgusunu da yürütür. İşlemler yalnızca SQL veritabanı türleri için oluşturulur.

Aşağıdaki tabloda, her veritabanı türü için işlemlerin oluşturulduğu yalıtım düzeyleri listelenir.

Veritabanı Türü Yalıtım Düzeyi Daha fazla bilgi
Azure SQL (veya) SQL Server Okundu Azure SQL
MySQL Yinelenebilir Okuma MySQL
PostgreSQL Okundu postgreSQL

İlgili içerik

  • GraphQL yapılandırma başvurusu
  • OpenAPI