Sayfalama

Sayfalanan her listenin üç metodu vardır. list bir sayfa getirir ve bir OpenEmail::Page döndürür. list_all cursor'ı tüm sayfalar boyunca izler ve tek bir Array döndürür. iterate aynı sayfaları her seferinde bir öğe olacak şekilde dolaşır: her öğeyi bir bloğa verir ya da blok vermezseniz bir Enumerator döndürür. Üçü de listenin filtrelerini, limit:, cursor: ve api_key: alır.

page = client.emails.list(status: "failed", limit: 50)page.items.each { |email| puts "#{email[:id]} #{email[:lastError]}" } failures = client.emails.list_all(status: "failed") client.emails.iterate(status: "failed") do |email|  puts email[:id]end puts failures.size, page.has_more?

Bir ad alanında birden fazla liste olduğu her yerde aynı üç ad, dolaştıkları listeye göre adlandırılarak tekrarlanır: emails üzerinde list_events, list_all_events ve iterate_events; webhooks üzerinde list_deliveries, list_all_deliveries ve iterate_deliveries ve benzerleri.

Bir sayfa bir Ruby Data nesnesidir; bu yüzden dondurulmuştur, değere göre karşılaştırılır ve to_h ile bir Hash'e dönüşür.

Bir blok verildiğinde iterate tüm sayfaları hemen dolaşır ve her öğeyi bloğa verir. Blok olmadan bir Enumerator döndürür ve siz onu tüketene kadar hiçbir şey getirmez. Her iki durumda da bir sonraki sayfayı ancak geçerli sayfanın tüm öğeleri verildikten sonra ister; bu yüzden erken duran her şey istekleri de durdurur: first(10) yalnızca on öğe için gereken kadar sayfa okur, find eşleşmede durur ve bir bloktaki break dolaşmayı bitirir.

latest = client.emails.iterate(status: "failed", limit: 100).first(10) invoice = client.emails.iterate(status: "failed").find do |email|  email.dig(:tags, :invoice) == "inv_2026_09_4192"end from_api = client.emails.iterate(status: "bounced").lazy.select { |email| email[:source] == "api" }.first(5) p latest.size, invoice&.fetch(:id), from_api.map { |email| email[:id] }

Doğrudan Enumerator üzerinde çağrılan select, map ya da count gibi her öğeye ihtiyaç duyan bir Enumerable metodu, list_all gibi dönmeden önce tüm sayfaları okur. Bunları zincirleyip yine de erken durabilmek için başa lazy koyun.

Bir cursor opaktır. Okuduğunuz son sayfanın next_cursor değerini saklayın ve daha sonraki bir istekte ya da başka bir süreçte oradan devam etmek için onu cursor: olarak geri geçirin. list_all ve iterate de cursor: alır ve dolaşmaya onun ardından başlar.

first_page = client.emails.list(status: "failed", limit: 25)saved = first_page.next_cursor if saved  rest = client.emails.list_all(status: "failed", cursor: saved)  puts rest.sizeend

limit: toplam değil, her sayfanın boyutudur. list üzerinde kaç satır döneceğidir. list_all ve iterate üzerinde her isteğin kaç satır istediğidir; bu yüzden daha büyük bir değer aynı satırlar için daha az gidiş dönüş anlamına gelir. Her listenin kendi aralığı ve varsayılanı vardır; çoğunlukla 1 ile 100 arasıdır ve hiçbir şey göndermezseniz 25'tir. Aralık dışındaki bir değer kırpılmaz, reddedilir. Her listenin sayfası kendi aralığını belirtir.

• —Bir sayfa has_more? değerinin false olduğunu söylediğinde.
• —Bir sayfa next_cursor taşımadığında, çünkü devamı olduğunu iddia edip hiçbir cursor belirtmeyen bir sayfa sonsuza dek döngüye girerdi.
• —API kendisine az önce verilen cursor'ı geri verdiğinde, aynı nedenle.

Her sayfa bir GET'tir; bu yüzden herhangi bir hata fırlatılmadan önce her okuma gibi kendi başına yeniden denenir. Yeniden denemelerden sonra da süren bir hata list_all dışına fırlatılır ve o ana kadar getirilen öğeler atılır. iterate içinde ise önceki sayfaların öğeleri o zamana kadar zaten verilmiştir; bu yüzden bloğun yaptığı işi iki kez çalışmaya karşı güvenli hâle getirin ya da list ile sayfalayıp her next_cursor değerini saklayın, böylece ikinci bir deneme ilkinin durduğu yerden başlayabilir.

threads.list ve drafts.list, list_all ve iterate metotlarıyla birlikte, bir cursor yerine API'nin pageToken ve nextPageToken değerleriyle sayfalar. Gem bu farkı gizler: tokenı cursor: olarak geçirin ve next_cursor üzerinden okuyun.

page = client.threads.list(folder: "inbox", limit: 50)later = client.threads.list(folder: "inbox", limit: 50, cursor: page.next_cursor) if page.has_more? p page.items.size, later&.items&.size

Birkaç liste satırlardan fazlasıyla yanıt verir ve OpenEmail::Page yerine kendine ait bir Data nesnesi döndürür.

Bazı listeler ofsetle, sayfa numarasıyla ya da kendilerine ait sayısal bir cursor ile sayfalar ve ayrıştırılmış gövdeyi bir OpenEmail::Page yerine geldiği gibi, data içeren bir Hash olarak döndürür. Bunların list_all ya da iterate metotları yoktur, bu yüzden sayfalamayı kendiniz yaparsınız.

offset = 0 loop do  batch = client.subscriptions.list(status: "active", limit: 50, offset:)  batch[:data].each { |row| puts "#{row[:senderEmail]} #{row[:total]}" }   break unless batch[:hasMore]   offset += batch[:data].sizeend