GraphQL API, daha belirli ve esnek sorgular kullanarak tam olarak ihtiyacınız olan verileri almanızı sağlayan bir araçtır. GraphQL API’nin ana faydalarından biri, tek bir istek kullanarak birçok farklı kaynak elde edebilmenizdir.
Crowdin GraphQL API’sine karşı sorgu çalıştırmak istediğiniz durumlarda, yardımı ile uygulamanızda herhangi bir kod yazmadan önce bile Crowdin ve Crowdin Enterprise web kullanıcı arayüzünden sorgular oluşturabileceğiniz, deneyebileceğiniz ve hata ayıklayabileceğiniz GraphQL Playground uygulamasını kullanmanızı öneririz.
Crowdin veya Crowdin Enterprise’da GraphQL API ile çalışmak için aşağıdaki erişim belirteçlerinden birini kullanın:
İsteklerinizde aşağıdaki başlığı kullandığınızdan emin olun:
Yetkilendirme: Taşıyıcı <ACCESS_TOKEN>
Yetkilendirmenin başarısız olması durumunda yanıt:
401 Yetkisiz
{
"error": {
"message": "Yetkisiz",
"code": 401
}
}
REST API’nin aksine, GraphQL API, gerçekleştirilen işlemlere bağlı olmaksızın sabit kalan sadece bir uç noktaya sahiptir.
Crowdin GraphQL uç noktası:
https://api.crowdin.com/api/graphql
Crowdin Enterprise GraphQL uç noktası:
https://{etkialanı}.api.crowdin.com/api/graphql
Crowdin GraphQL API, Crowdin sunucularına aşırı veya kötüye kullanım amaçlı çağrıları önlemek için sınırlamalara sahiptir.
Tüm GraphQL API çağrıları, şema doğrulamasını geçmek için aşağıdaki gereksinimlere uymak zorundadır:
ilk veya son bağımsız değişkenini sağlamak zorundadır.İlk ve son değerleri 1-10.000 arasında olmak zorundadır.Aşağıdaki örneklerde, bir çağrıdaki düğümlerin nasıl hesaplandığını gözden geçirebilirsiniz.
Basit sorgu:
query {
viewer {
projects(first: 50) {
edges {
node {
name
files(first: 10) {
totalCount
edges {
node {
name
type
}
}
}
}
}
}
}
}
Hesaplama:
50 = 50 proje
+
50 x 10 = 500 dosya
= 550 toplam düğüm
Karmaşık sorgu:
query {
viewer {
projects(first: 50) {
edges {
node {
files(first: 20) {
edges {
node {
strings(first: 10) {
edges {
node {
... on PlainSourceString {
text
}
... on ICUSourceString {
text
}
... on PluralSourceString {
plurals {
one
other
}
}
... on AssetSourceString {
text
}
}
}
}
}
}
}
translations(first: 20, languageId: "tr") {
edges {
node {
... on PlainStringTranslation {
text
}
... on ICUStringTranslation {
text
}
... on PluralStringTranslation {
pluralForm
text
}
... on AssetStringTranslation {
text
}
}
}
}
}
}
}
}
}
Hesaplama:
50 = 50 proje
+
50 x 20 = 1.000 dosya
+
50 x 20 x 10 = 10.000 dizgi
+
50 x 20 = 1.000 çeviri
= 12.050 toplam düğüm
GraphQL API sınırı, REST API için ayarlanan fiyat sınırlarına kıyasla oldukça farklıdır.
Yukarıda bahsedildiği gibi, sadece bir GraphQL çağrısı kullanarak ve birden çok REST çağrısı yürütme ihtiyacını değiştirerek aynı miktarda veri alabilirsiniz. Tek bir karmaşık GraphQL çağrısı, binlerce REST isteğine eşdeğer olabilir ve REST API fiyat sınırını aşamazken, hesaplaması Crowdin sunucuları için aynı derecede pahalı olabilir.
GraphQL API, bir çağrının fiyat sınırı skorunu hesaplayarak bir sorgunun sunucu maliyetini tam olarak göstermek için normalleştirilmiş bir puan ölçeği kullanır. Bu skor, bir ana bağlantı ve alt bağlantısındaki ilk ve son bağımsız değişkenleri içerir.
ilk ve son bağımsız değişkenlerini kullanır.GraphQL API fiyat sınırı saatte 5.000 puana ayarlanmıştır. GraphQL API ve REST API farklı fiyat sınırları kullandığından, saatte 5.000 puan, saatte 5.000 çağrı ile aynı değildir.
GraphQL API’sini kullanırken fiyat sınırı durumunu denetlemek için rateLimit nesnesindeki alanları sorgulayın:
query {
viewer {
username
}
rateLimit {
limit
cost
remaining
resetAt
}
}
limit – 60 dakikalık bir aralıkta kullanıcının tüketmesine izin verilen en fazla puan sayısını döndürür.cost – fiyat sınırına göre şu anki çağrı için puan maliyetini döndürür.remaining – şu anki fiyat sınırı aralığında kalan puan sayısını döndürür.resetAt – UTC dönemi saniye cinsinden şu anki fiyat aralığının sıfırlandığı zamanı döndürür.rateLimit nesnesini sorgulamak size bir çağrının puanını verebilirken, sınıra göre sayılır. Bu duruma geçici bir çözüm bulmak için bir çağrının puanını önceden tahmin edebilirsiniz. Aşağıdaki hesaplamayı kullanarak, rateLimit { cost } tarafından döndürülen maliyetle yaklaşık olarak aynı maliyeti elde edebilirsiniz.
ilk veya son bağımsız değişken sınırlarına ulaşacağını varsayalım.İşte örnek bir sorgu ve skor hesaplaması:
query {
viewer {
username
projects(first: 100) {
edges {
node {
id
files(first: 50) {
edges {
node {
id
strings(first: 60) {
edges {
node {
... on PlainSourceString {
id
text
}
... on ICUSourceString {
id
text
}
... on PluralSourceString {
id
plurals {
one
other
}
}
... on AssetSourceString {
id
text
}
}
}
}
}
}
}
}
}
}
}
}
Şimdi, 5.101 toplamını 100’e bölün ve yuvarlayın. Sonuç olarak, 51 olan sorgunun son skorunu alırsınız.
Sayfalandırma, GraphQL’de daha büyük bir koleksiyondan bir veri alt kümesini almanızı sağlayan, bilgileri yönetmeyi ve görüntülemeyi kolaylaştıran temel bir kavramdır.
Bu bölümde örnek olarak projects alanına odaklanarak Crowdin GraphQL API’de sayfalandırmanın nasıl kullanılacağını inceleyeceğiz.
Sayfalandırmayı kullanmanın ayrıntılarına dalmadan önce bazı temel terimleri açıklığa kavuşturalım:
hasNextPage, hasPreciousPage, startCursor ve endCursor gibi alanları içerir.Şimdi Crowdin GraphQL API’sindeki projects alanıyla sayfalandırmayı kullanmaya odaklanalım.
User türü içindeki projects alanı, bir kullanıcıyla ilişkilendirilmiş projeleri sorgulamak için kullanılır. Sonuçların sayfalandırılmasını denetlemenizi sağlayan çeşitli giriş parametrelerini kabul eder. Bu parametreler şunlardır:
after – Projelerin listesinde sorgunun nereden başlaması gerektiğini gösteren bir imleç.first – Belirtilen imleçten sonra alınacak proje sayısı.before – Sorgunun nerede bitmesi gerektiğini gösteren bir imleç.last – Belirtilen imleçten önce alınacak proje sayısı.Aşağıdaki örnek sorgu, sağlanan imleçten (cursor_string) başlayarak kimliği doğrulanmış kullanıcıyla ilişkilendirilmiş ilk on projeyi ister. Yanıt, proje verilerini içeren edges diziliminin yanı sıra sayfalandırma denetimi için pageInfo ve totalCount alanlarını içerecektir.
query {
viewer {
projects(
after: "cursor_string", # Geçerli bir `after` imleciyle değiştirin
first: 10
) {
edges {
node {
id
name
description
# Gerektiğinde daha fazla alan ekleyin
}
cursor
}
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
totalCount
}
}
}
Yukarıdaki sorgu için bir yanıt örneğini burada bulabilirsiniz:
{
"data": {
"viewer": {
"projects": {
"edges": [
{
"node": {
"id": 1,
"name": "Umbrella",
"description": "Resmi Umbrella Çeviri Projesi"
},
"cursor": "MA=="
},
{
"node": {
"id": 2,
"name": "Umbrella iOS",
"description": "Resmi Umbrella iOS Uygulaması Çeviri Projesi"
},
"cursor": "MQ=="
}
],
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MA==",
"endCursor": "MQ=="
},
"totalCount": 5
}
}
}
}
hasNextPage – pageInfo’daki bu alan, bir sonraki sayfa için daha fazla projenin mevcut olup olmadığını gösterir.hasPreviousPage – pageInfo’daki bu alan, önceki sayfa için daha fazla projenin mevcut olup olmadığını gösterir.startCursor – Şu anki sonuç kümesindeki ilk projeyi gösteren imleç.endCursor – Şu anki sonuç kümesindeki son projeyi gösteren imleç.totalCount – Kullanıcıyla ilişkilendirilmiş projelerin toplam sayısı.Veri kümenizdeki sayfalarda geriye doğru gitmenizi gerektirebilecek senaryolar vardır. Bu, eski verilerin gözden geçirilmesi, düzeltilmesi veya değiştirilmesi vb. gibi çeşitli nedenlerle gerekli olabilir.
Sayfalarda geriye doğru gezinmek için last ve before parametrelerini kullanabilirsiniz. last parametresi listenin sonundaki öğe sayısını belirtir ve before parametresi almak istediğiniz ilk öğenin imlecini alır. İşte bir örnek:
query {
viewer {
projects(
last: 10,
before: "cursor_of_first_item" # Geçerli bir `before` imleciyle değiştir
) {
edges {
node {
id
name
description
# Gerektiğinde daha fazla alan ekleyin
}
}
}
}
}
Crowdin GraphQL, verileri süzmek ve sıralamak (düzenlemek) için yetenekler sunarak, almak istediğiniz veri seçimini daraltmanızı ve bunları belirli bir sıraya göre düzenlemenizi sağlar.
Sayfalandırmada olduğu gibi bu bölümde, örnek olarak projects alanına odaklanarak Crowdin GraphQL API’de süzme ve sıralamanın nasıl kullanılacağını keşfedeceğiz.
Süzme, daha büyük bir veri kümesinden bir veri alt kümesini seçmek için ölçütü belirleme işlemidir. Crowdin GraphQL’de süzme, sorgu sonuçlarınızı belirli koşullara göre daraltmanızı sağlar. Bu, özellikle belirli gereksinimleri veya özellikleri karşılayan verileri almak istediğinizde kullanışlıdır.
Crowdin GraphQL, projeleri çeşitli özelliklere dayanarak süzmenize izin veren ProjectFilterInput türünü sağlar. Süzebileceğiniz bazı temel öznitelikler şunlardır:
and – Birden çok süzme ölçütünü birleştiren mantıksal bir bağlaç.or – Birden çok süzme ölçütünü birleştiren mantıksal bir ayrım.id – Eşitlik, büyüktür veya küçüktür gibi çeşitli koşulları kullanarak proje kimliğine göre süzün.userId – Projeleri, kendileriyle ilişkilendirilmiş kullanıcı kimliğine göre süzün.name – Eşitliği, kapsamı denetleme veya belirli bir metinle başlama seçenekleriyle projeyi adına göre süzün.identifier – Ada göre süzmeye benzer şekilde proje tanımlayıcısına göre süzün.description – Eşitlik, kapsama veya belirli bir metinle başlama seçenekleriyle projeyi açıklamalarına göre süzün.publicDownloads – Ortak indirmelerin etkin olup olmamasına dayanarak projeleri süzün.languageAccessPolicy – Projeleri dil erişim ilkelerine göre süzün (örn. “open” veya “moderate”).visibility – Projeleri görünürlüklerine dayanarak süzün (örn. “open” veya “private”).createdAt – Tarihle ilgili çeşitli koşulları kullanarak projeleri oluşturulma tarihlerine göre süzün.updatedAt – Projeleri son güncelleme tarihlerine göre süzün.lastActivityAt – Projeleri son etkinlik tarihlerine göre süzün.Süzme, sorgularınızda ihtiyaç duyduğunuz verileri tam olarak hedeflemenin esnek bir yoludur. Sorgunuzu daha da hassaslaştırmak amacıyla birden çok süzme koşulunu birleştirmek için and ve or gibi mantıksal işleticileri kullanabilirsiniz.
Belirli bir tarihten sonra ve “private” görünürlük ayarıyla oluşturulan projeleri almak için şunun gibi bir süzgeç girişi oluşturabilirsiniz:
query {
viewer {
projects(
first: 10,
filter: {
createdAt: { gt: "2023-01-01T00:00:00Z" }
and: { visibility: { equals: private } }
}
) {
edges {
node {
id
name
description
# Gerektiğinde daha fazla alan ekleyin
}
}
}
}
}
Bu süzgeç, her iki koşulu da karşılayan projeleri döndürür: 1 Ocak 2023’ten sonra oluşturulmuş ve “private” görünürlüğe ayarlanmış.
Sıralama, sorgu sonuçlarının sunulacağı sıranın belirtilmesini içerir. Sonuçların sayısını azaltmaz ancak bunları belirli bir sıraya göre düzenler. Crowdin GraphQL, verileri proje adı, oluşturulma tarihi veya diğer ilgili etkenler gibi özniteliklere dayanarak sıralamak için seçenekler sunar.
Crowdin GraphQL’deki ProjectOrderInput türü, sorgu sonuçlarınız için sıralama düzenini belirtmenizi sağlar. Projeleri aşağıdaki özniteliklere dayanarak sıralayabilirsiniz:
id – Projeleri benzersiz tanımlayıcılarına göre sıralayın.userId – Projeleri, onları oluşturan kullanıcının tanımlayıcısına göre sıralayın.name – Projeleri adlarına göre sıralayın.identifier – Projeleri tanımlayıcılarına göre sıralayın.description – Projeleri açıklamalarına göre sıralayın.publicDownloads – Projeleri ortak indirme ayarlarına göre sıralayın.languageAccessPolicy – Projeleri dil erişim ilkelerine göre sıralayın.visibility – Projeleri görünürlük ayarlarına göre sıralayın.createdAt – Projeleri oluşturulma tarihlerine göre sıralayın.updatedAt – Projeleri son güncelleme tarihlerine göre sıralayın.lastActivityAt – Projeleri son etkinlik tarihlerine göre sıralayın.Sıralama düzeninin artan (“asc”) veya azalan (“desc”) düzende olacağını belirleyerek, verilerin nasıl sunulduğu üzerinde tam denetim sahibi olabilirsiniz.
Projeleri adlarına göre azalan düzende sıralanmış almak için şunun gibi bir sıralama girişi oluşturabilirsiniz:
query {
viewer {
projects(
first: 10
order: [{ name: desc }]
) {
edges {
node {
id
name
description
# Gerektiğinde daha fazla alan ekleyin
}
}
}
}
}
Bu sıralama düzeni, projeleri adlarının ters alfabetik sırasına göre sunacaktır.
Crowdin GraphQL, sorgularınızı tam olarak uyarlamak için hem süzmeyi hem de sıralamayı birleştirmenizi sağlar. Belirli ölçütleri karşılayan bir alt kümeyi seçmek için önce verileri süzebilir ve ardından sonuçları istediğiniz sıraya göre sıralayabilirsiniz. Bu birleşim, verileri özel gereksinimlerinize göre almanızı ve düzenlemenizi sağlar.
Belirli bir tarihten sonra oluşturulan projeleri “moderate” dil erişim ilkesiyle almak ve son etkinlik tarihlerine göre artan sırada sıralamak için şöyle bir sorgu oluşturabilirsiniz:
query {
viewer {
projects(
first: 10
filter: {
createdAt: { gt: "2023-01-01T00:00:00Z" }
and: { languageAccessPolicy: { equals: moderate } }
},
order: [{ lastActivityAt: asc }]
) {
edges {
node {
id
name
description
# Gerektiğinde daha fazla alan ekleyin
}
}
}
}
}
Bu sorgu, süzme koşullarını karşılayan projeleri döndürecek ve son etkinlik tarihlerine dayanarak artan sırada sunacak.