Faqosja

Çdo listë që faqoset ka tri metoda. list merr një faqe dhe kthen një OpenEmail::Page. list_all ndjek cursor-in nëpër të gjitha faqet dhe kthen një Array të vetëm. iterate i përshkon të njëjtat faqe një element në një kohë: ia jep çdo element një blloku, ose kthen një Enumerator kur nuk i jepni bllok. Të tria marrin filtrat e listës, limit:, cursor: dhe api_key:.

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?

Të njëjtat tri emra përsëriten kudo ku një hapësirë emrash ka më shumë se një listë, të emërtuar sipas listës që përshkojnë: list_events, list_all_events dhe iterate_events te emails, list_deliveries, list_all_deliveries dhe iterate_deliveries te webhooks, e kështu me radhë.

Një faqe është një objekt Ruby Data, ndaj është e ngrirë, krahasohet sipas vlerës dhe shndërrohet në Hash me to_h.

Kur i jepet një bllok, iterate i përshkon menjëherë të gjitha faqet dhe ia jep bllokut çdo element. Pa bllok, kthen një Enumerator dhe nuk merr asgjë derisa ta konsumoni. Në të dyja rastet e kërkon faqen e radhës vetëm pasi të jetë dhënë çdo element i faqes aktuale, ndaj çdo gjë që ndalon herët i ndal edhe kërkesat: first(10) lexon vetëm aq faqe sa u duhen dhjetë elementeve, find ndalon te përputhja, dhe break në një bllok e përfundon përshkimin.

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

Një metodë Enumerable që ka nevojë për çdo element, si select, map ose count e thirrur drejtpërdrejt mbi Enumerator-in, lexon të gjitha faqet para se të kthehet, ashtu si list_all. Vendosni lazy përpara për t’i zinxhiruar ato dhe për të ndaluar prapëseprapë herët.

Një cursor është i errët. Ruani next_cursor e faqes së fundit që lexuat dhe jepeni prapa si cursor: për të vazhduar prej andej, në një kërkesë të mëvonshme ose në një proces tjetër. list_all dhe iterate marrin gjithashtu cursor: dhe e nisin përshkimin pas tij.

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: është madhësia e çdo faqeje, jo një total. Te list është numri i rreshtave që kthehen. Te list_all dhe iterate është numri që kërkon çdo kërkesë, ndaj një vlerë më e madhe do të thotë më pak vajtje-ardhje për të njëjtët rreshta. Çdo listë ka diapazonin dhe parazgjedhjen e vet, më shpesh nga 1 deri në 100 dhe 25 kur nuk dërgoni asgjë, dhe një vlerë jashtë diapazonit refuzohet në vend që të kufizohet. Faqja e çdo liste jep diapazonin e saj.

• —Kur një faqe thotë se has_more? është false.
• —Kur një faqe nuk mbart next_cursor, sepse një faqe që pretendon se ka më shumë pa emërtuar asnjë cursor do të përsëritej në cikël përgjithmonë.
• —Kur API-ja kthen cursor-in që sapo iu dha, për të njëjtën arsye.

Çdo faqe është një GET, ndaj, si çdo lexim, riprovohet më vete para se të ngrihet ndonjë gabim. Një dështim që u mbijeton riprovave ngrihet jashtë list_all, dhe elementet e marra tashmë hidhen poshtë. Te iterate, elementet e faqeve të mëparshme janë dhënë tashmë deri atëherë, ndaj bëjeni atë që kryen blloku të sigurt për t’u ekzekutuar dy herë, ose faqosni me list dhe ruani çdo next_cursor, që një përpjekje e dytë të nisë aty ku ndaloi e para.

threads.list dhe drafts.list, bashkë me list_all dhe iterate të tyre, faqosin me pageToken dhe nextPageToken të API-së në vend të një cursor-i. Gem-i e fsheh këtë ndryshim: jepeni token-in si cursor: dhe lexojeni nga next_cursor.

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

Disa lista përgjigjen me më shumë se rreshta dhe kthejnë një objekt Data të tyrin në vend të OpenEmail::Page.

Disa lista faqosin sipas zhvendosjes (offset), sipas numrit të faqes ose sipas një cursor-i numerik të tyrin, dhe kthejnë trupin e analizuar ashtu siç erdhi, një Hash me data, në vend të një OpenEmail::Page. Nuk kanë list_all ose iterate, ndaj faqosjen e bëni vetë.

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