Yeniden denemeler ve idempotency
Neler yeniden denenir, neler bilerek denenmez ve yeniden denenen bir gönderim neden kopya oluşturamaz.
Gönderimler
İstemci her gönderime (emails->send, emails->sendBatch, templates->send ve broadcasts->send) bir Idempotency-Key ekler; bu anahtar çağrı başına bir kez oe- ve rastgele bir UUID olarak üretilir ve o çağrının yeniden denemelerinde yeniden kullanılır. API, herhangi bir şeyi sevk etmeden önce bu anahtarı sahiplenir; böylece bir yeniden deneme ikinci bir ileti göndermek yerine asıl iletiyi yeniden oynatır, bilerek yapılan iki send çağrısı ise yine iki kez gönderir. Bunlar farklı niyetlerdir ve farklı kalırlar.
Bu garantiyi süreçler arasına yaymak için kendi idempotencyKey: değerinizi geçirin; böylece çöküp yeniden çalışan bir iş, gönderimlerini tekrarlamak yerine yeniden oynatır. Bir yeniden oynatma, replayed değeri true olarak ve saklanan iletinin şu anki hâliyle yanıt verir.
$invoiceId = 'inv_2026_09_4192'; $sent = $client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'subject' => 'Your September invoice', 'text' => 'Invoice attached.',], idempotencyKey: 'invoice:' . $invoiceId); echo $sent['id'], ' ', ($sent['replayed'] ?? false) ? 'replayed' : 'sent', PHP_EOL;Anahtarı, gönderimi gerekli kılan şeyden türetin. Asla bir saatten değil. Bir anahtarı farklı bir gövdeyle yeniden kullanmak sessizce yeniden oynatılmaz, 422 idempotency_key_reuse ile reddedilir. Bir anahtar harf, rakam, _, ., : ya da - karakterlerinden oluşan 1 ile 255 karakter arasındadır; başka her şey 400 invalid_idempotency_key verir.
Diğer her şey
Her GET yeniden denenir. Bir yazma işlemi yalnızca ikinci bir özdeş isteğin ilkinden farklı bir anlam taşıyamayacağı durumlarda yeniden denenir; bir gönderim de bu koşulu sağlar, çünkü idempotency anahtarı bir tekrarı yeniden oynatmaya dönüştürür.
| Çağrı | Yeniden denenir | Neden |
|---|---|---|
| Her GET | Evet | Hiçbir şey değişmez. |
| emails->send, emails->sendBatch, templates->send, broadcasts->send | Evet | Bir idempotency anahtarı, tekrarı yeniden oynatmaya dönüştürür. |
| emails->cancel, emails->reschedule, broadcasts->cancel, forms->pause, forms->resume, threads->restore | Evet | Adlandırılmış bir durumun saf biçimde atanması. |
| threads->update, threads->trash | Evet | Bir etiket ataması. İki kez uygulamak, bir kez uygulamakla aynıdır. |
| threads->snooze, threads->unsnooze | Evet | Uyanma anı gövdenin içindedir; varış zamanından türetilmez. |
| emails->update, labels->update, webhooks->update, settings->update, roles->update, members->update, domains->update, domains->updateAddress, domains->updateAddressForward, contacts->update, audiences->update, keys->update, forms->update, branding->update, threads->updateNote, chats->rename, account->setEmailNotification, account->setPushMuted, appHost->set, workspaces->setActive | Evet | Adlandırılmış alanların saf biçimde atanması. |
| members->grantAddress, members->grantDomain, rules->reorder, threads->reorderNotes | Evet | Bir yetki verme işlemi upsert'tür ve bir sıralama her zaman eksiksiz belirtilir. |
| templates->publish, forms->publish, imports->start | Evet | Zaten yayımlanmış olanı yayımlamak ya da zaten başlamış bir içe aktarmayı başlatmak onu değiştirmeden döndürür. |
| templates->preview, templates->render, broadcasts->preview, rules->test | Evet | Yalnızca işler, sayar ya da değerlendirirler; hiçbir şey yazmazlar. |
| domains->verify, appHost->verify, senders->research | Evet | Tekrarlanan bir denetim, yapıldığı zaman dışında hiçbir şeyi değiştirmez. |
| contacts->save, contacts->setAudiences, contacts->removePhoto, contacts->block, contacts->unblock, contacts->deleteMany, keys->revoke, files->revokeLink, files->revokeAllLinks, appHost->delete, account->removePhoto, branding->removeImage, domains->removeLogo, domains->removeLogoCertificate, domains->removeAddressPhoto, account->acceptInvitation, account->declineInvitation, forms->approveSubmission, subscriptions->move | Evet | Her biri nihai sonucu belirtir; bu yüzden ikinci bir çağrı, ilkinin bıraktığını bırakır. |
| audiences->addContact, audiences->addContacts, audiences->removeContacts, audiences->importContacts, suppressions->add, domains->createAddress | Evet | Bir tekrar, ilk çağrının işini zaten yapılmış bulur ve iki kez yapmak yerine bunu bildirir. |
| contacts->setPhoto, account->setPhoto, branding->uploadImage, domains->setLogo, domains->setLogoCertificate, domains->setAddressPhoto, imports->uploadChunk | Evet | Yeniden gönderilen baytlar, ilk denemenin sakladığının yerini alır. |
| drafts->create, labels->create, webhooks->create, templates->create, rules->create, roles->create, tempMail->create, files->upload | Hayır | Bir yeniden deneme geriye iki nesne bırakır. |
| drafts->update | Hayır | Gönderdiğiniz id'yi yeniden kullanmak yerine, her yazmanın sonucundaki id'yi okuyun. |
| drafts->delete, labels->delete, webhooks->delete, templates->delete, rules->delete, roles->delete, members->remove, members->revokeAddress, tempMail->delete, tempMail->deleteMessage | Hayır | Kaybolan bir yanıtın ardından yapılan yeniden deneme, başarılı olmuş bir iş için başarısızlık bildirir. |
| webhooks->rotateSecret | Hayır | İkinci bir döndürme, ilk denemenin döndürdüğü gizli anahtarı geçersiz kılar. |
| webhooks->test | Hayır | İkinci bir yapay teslimat gönderirdi. |
| webhooks->replayDelivery | Hayır | Olayı alıcınıza ikinci kez gönderirdi. |
| emails->translate, emails->compose, emails->rewrite, emails->suggestSubject | Hayır | Her biri model çağrıları harcar; bu yüzden yanıtlanmamış bir istekten sonraki yeniden deneme aynı yanıt için iki kez ödeme yapar. |
| security->beginStepUp, security->verifyStepUp | Hayır | Bir yeniden deneme ikinci bir e-posta gönderebilir ya da kod için ikinci bir denemeyi harcayabilir. |
| GET olmayan diğer her çağrı | Hayır | Bir kez gönderilir; başarısızlık tekrarlanmak yerine bildirilir. |
Geri çekilme
- İstemcideki
maxRetries:ile sınırlıdır; varsayılan olarak iki ek denemedir.maxRetries: 0yeniden denemeleri kapatır. - Yalnızca bir ağ hatasının ya da
408,500,502,503veya504yanıtının ardından. Bir429yalnızcaRetry-Aftertaşıdığında yeniden denenir; bu API böyle bir başlık göndermediğinden, hız sınırı doğrudan hata fırlatır. Diğer tüm durum kodları anında hata fırlatır. - Yarım saniyeden sekiz saniyeye kadar üstel, rastgele sapma (jitter) ile: her bekleme, o üst sınırın yarısı ile tamamı arasında rastgele bir noktadır; böylece bir istemci filosu toparlanma anında yeniden senkronize olmaz.
- Her iki biçimiyle de, delay-seconds ve HTTP-date,
Retry-Aftertarafından ayarlanır. Sunucu bir bekleme süresi belirttiğinde istemci geri çekilme uygulamak yerine tam olarak o kadar bekler. - Bir dakikadan uzun bekleme isteyen bir sunucu, istemciye beklemesini değil durmasını söylüyor kabul edilir; bu yüzden istisna, üzerinde
retryAfterSecondsile fırlatılır. Sunucunun istediğinden daha erken geri dönmek bu isteğe uymamak olurdu. - Zaman aşımı da diğerleri gibi bir ağ hatasıdır; bu yüzden tekrarlanması güvenli bir çağrı bir zaman aşımından sonra yeniden denenir ve
timeout:her denemeye baştan uygulanır. - Beklemeler çağrının içindeki
sleepveusleepçağrılarıdır; bu yüzden betik de bekler ve çağrı yalnızca son denemesi bittiğinde döner ya da istisna fırlatır. Bir kişinin beklediği bir web isteğindetimeout:vemaxRetries:değerlerini düşük tutun.