Halaman ini menjelaskan cara alat Cloud Storage mencoba ulang permintaan yang gagal dan cara menyesuaikan perilaku percobaan ulang. Bagian ini juga menjelaskan pertimbangan dalam mencoba ulang permintaan.
Ringkasan
Ada dua faktor yang menentukan apakah sebuah permintaan aman untuk dicoba ulang:
- Respons yang Anda terima dari permintaan.
- Idempotensi permintaan.
Tanggapan
Respons yang Anda terima dari permintaan menunjukkan apakah akan berguna untuk mencoba ulang permintaan tersebut. Respons yang terkait dengan masalah sementara umumnya dapat dicoba ulang. Di sisi lain, respons yang terkait dengan error permanen menunjukkan bahwa Anda perlu melakukan perubahan, seperti perubahan otorisasi atau konfigurasi, sebelum mencoba ulang permintaan tersebut. Respons berikut menunjukkan masalah sementara yang akan berguna jika Anda mencoba ulang permintaan:
- Kode respons
408
,429
, dan5xx
HTTP. - Waktu tunggu soket dan TCP terputus.
Untuk mengetahui informasi selengkapnya, lihat status dan kode error untuk JSON dan XML.
Idempotensi
Permintaan yang idempoten berarti permintaan dapat dilakukan berulang kali dan resource yang ditargetkan akan selalu dalam status akhir yang sama. Misalnya, permintaan listingan selalu idempoten, karena permintaan tersebut tidak mengubah resource. Di sisi lain, pembuatan notifikasi Pub/Sub baru tidak pernah bersifat idempoten, karena permintaan tersebut akan membuat ID notifikasi baru setiap kali permintaan berhasil.
Berikut adalah contoh kondisi yang membuat operasi bersifat idempoten:
Operasi memiliki efek yang dapat diamati yang sama pada resource yang ditargetkan, bahkan saat operasi tersebut terus diminta.
Operasi hanya berhasil sekali.
Operasi tidak memiliki efek yang dapat diamati pada status resource yang ditargetkan.
Saat menerima respons yang dapat dicoba ulang, Anda harus mempertimbangkan idempotensi permintaan, karena mencoba ulang permintaan yang tidak idempoten dapat menyebabkan kondisi race dan konflik lainnya.
Idempotensi bersyarat
Subset permintaan bersifat bersifat idempoten bersyarat, yang berarti permintaan tersebut hanya idempoten jika menyertakan argumen opsional tertentu. Operasi yang dapat dicoba ulang secara bersyarat hanya boleh dicoba ulang secara default jika kasus kondisi terpenuhi. Cloud Storage menerima prasyarat dan ETag sebagai kasus kondisi untuk permintaan.
Idempotensi operasi
Tabel berikut ini mencantumkan operasi Cloud Storage yang termasuk dalam setiap kategori idempotensi.
Idempotensi | Operations |
---|---|
Selalu idempoten |
|
Idempoten bersyarat |
|
Tidak pernah idempoten |
|
Cara alat Cloud Storage mengimplementasikan strategi percobaan ulang
Konsol
Konsol Google Cloud mengirimkan permintaan ke Cloud Storage atas nama Anda dan menangani backoff yang diperlukan.
Command line
Perintah gcloud storage
dan gsutil mencoba ulang error yang tercantum di bagian Respons tanpa mengharuskan Anda melakukan tindakan tambahan.
Anda mungkin harus mengambil tindakan untuk error lainnya, seperti berikut ini:
Kredensial tidak valid atau izin tidak memadai.
Jaringan tidak dapat dijangkau karena masalah konfigurasi proxy.
Setiap operasi yang gagal dalam perintah gsutil tempat Anda menggunakan flag level atas
-m
.
Untuk error yang dapat dicoba ulang, alat command line mencoba ulang permintaan menggunakan strategi backoff eksponensial biner yang terpotong. Jumlah default percobaan ulang maksimum adalah 32 untuk gcloud CLI dan 23 untuk gsutil.
Library klien
C++
Secara default, operasi mendukung percobaan ulang untuk kode error HTTP berikut, serta error soket yang menunjukkan koneksi terputus atau tidak pernah berhasil dibuat.
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Semua setelan backoff eksponensial dan percobaan ulang di library C++ dapat dikonfigurasi. Jika algoritma yang diimplementasikan dalam library tidak mendukung kebutuhan Anda, Anda dapat memberikan kode kustom untuk mengimplementasikan strategi Anda sendiri.
Setelan | Nilai default |
---|---|
Percobaan ulang otomatis | Benar |
Waktu maksimum untuk percobaan ulang permintaan | 15 menit |
Waktu tunggu (backoff) awal | 1 detik |
Pengganda waktu tunggu per iterasi | 2 |
Jumlah waktu tunggu maksimum | 5 menit |
Secara default, library C++ akan mencoba ulang semua operasi yang memiliki error yang dapat dicoba ulang, bahkan untuk operasi yang tidak pernah idempoten dan dapat menghapus atau membuat beberapa resource jika berhasil berulang kali. Untuk mencoba ulang operasi idempoten saja, gunakan kelas google::cloud::storage::StrictIdempotencyPolicy
.
C#
Library klien C# menggunakan backoff eksponensial secara default.
Go
Secara default, operasi mendukung percobaan ulang untuk error berikut ini:
- Error koneksi:
io.ErrUnexpectedEOF
: Hal ini dapat terjadi karena masalah jaringan yang bersifat sementara.url.Error
yang berisiconnection refused
: Hal ini dapat terjadi karena masalah jaringan yang bersifat sementara.url.Error
yang berisiconnection reset by peer
: Ini berarti Google Cloud telah mereset koneksi.net.ErrClosed
: Ini berarti Google Cloud telah menutup koneksi.
- Kode HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Error yang mengimplementasikan antarmuka
Temporary()
dan memberikan nilaierr.Temporary() == true
- Salah satu error di atas yang telah digabungkan menggunakan penggabungan error Go 1.13
Semua setelan backoff eksponensial di library Go dapat dikonfigurasi. Secara default, operasi di Go menggunakan setelan berikut untuk backoff eksponensial (defaultnya diambil dari gax):
Setelan | Nilai default (dalam detik) |
---|---|
Percobaan ulang otomatis | True jika idempoten |
Jumlah maksimum percobaan | Tak terbatas |
Penundaan percobaan ulang awal | 1 detik |
Pengganda penundaan percobaan ulang | 2.0 |
Penundaan percobaan ulang maksimum | 30 seconds |
Total waktu tunggu (bagian dari upload yang dapat dilanjutkan) | 32 detik |
Total waktu tunggu (semua operasi lainnya) | Tak terbatas |
Secara umum, percobaan ulang akan berlanjut tanpa batas waktu kecuali jika konteks
pengendalian dibatalkan, klien ditutup, atau terjadi error yang bersifat
non-sementara. Agar percobaan ulang tidak dilanjutkan, gunakan waktu tunggu konteks atau pembatalan. Satu-satunya pengecualian untuk perilaku ini adalah saat melakukan upload
yang dapat dilanjutkan menggunakan Writer, dengan data
yang cukup besar sehingga memerlukan beberapa permintaan. Dalam skenario ini, waktu tunggu setiap bagian akan habis dan berhenti mencoba ulang setelah 32 detik secara default. Anda dapat menyesuaikan waktu tunggu default dengan mengubah Writer.ChunkRetryDeadline
.
Ada sebagian operasi Go yang idempoten bersyarat (aman untuk dicoba ulang dalam kondisi tertentu). Operasi ini hanya akan dicoba ulang jika memenuhi kondisi tertentu:
GenerationMatch
atauGeneration
- Aman untuk dicoba ulang jika prasyarat
GenerationMatch
diterapkan ke panggilan, atau jikaObjectHandle.Generation
ditetapkan.
- Aman untuk dicoba ulang jika prasyarat
MetagenerationMatch
- Aman untuk dicoba ulang jika prasyarat
MetagenerationMatch
diterapkan ke panggilan.
- Aman untuk dicoba ulang jika prasyarat
Etag
- Aman untuk dicoba ulang jika metode menyisipkan
etag
ke dalam isi permintaan JSON. Hanya digunakan diHMACKeyHandle.Update
jikaHmacKeyMetadata.Etag
telah ditetapkan.
- Aman untuk dicoba ulang jika metode menyisipkan
RetryPolicy
ditetapkan ke RetryPolicy.RetryIdempotent
secara default. Lihat bagian
Menyesuaikan percobaan ulang di bawah untuk mengetahui contoh cara mengubah
perilaku percobaan ulang default.
Java
Secara default, operasi mendukung percobaan ulang untuk error berikut ini:
- Error koneksi:
Connection reset by peer
: Ini berarti Google Cloud telah mereset koneksi.Unexpected connection closure
: Ini berarti Google Cloud telah menutup koneksi.
- Kode HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Semua setelan backoff eksponensial di library Java dapat dikonfigurasi. Secara default, operasi melalui Java menggunakan setelan berikut untuk backoff eksponensial:
Setelan | Nilai default (dalam detik) |
---|---|
Percobaan ulang otomatis | True jika idempoten |
Jumlah maksimum percobaan | 6 |
Penundaan percobaan ulang awal | 1 detik |
Pengganda penundaan percobaan ulang | 2.0 |
Penundaan percobaan ulang maksimum | 32 detik |
Total Waktu Tunggu | 50 detik |
Waktu Tunggu RPC Awal | 50 detik |
Pengganda Waktu Tunggu RPC | 1.0 |
Waktu Tunggu RPC Maksimum | 50 detik |
Waktu Tunggu Koneksi | 20 detik |
Waktu Tunggu Pembacaan | 20 detik |
Untuk informasi selengkapnya tentang parameter di atas, lihat dokumentasi
referensi Java untuk RetrySettings.Builder
dan
HttpTransportOptions.Builder
.
Ada sebagian operasi Java yang idempoten bersyarat (aman untuk dicoba ulang dalam kondisi tertentu). Operasi tersebut hanya melakukan percobaan ulang jika menyertakan argumen tertentu:
ifGenerationMatch
ataugeneration
- Aman untuk dicoba ulang jika
ifGenerationMatch
ataugeneration
diteruskan sebagai opsi ke metode ini.
- Aman untuk dicoba ulang jika
ifMetagenerationMatch
- Aman untuk dicoba ulang jika
ifMetagenerationMatch
diteruskan sebagai opsi.
- Aman untuk dicoba ulang jika
StorageOptions.setStorageRetryStrategy
ditetapkan ke
StorageRetryStrategy#getDefaultStorageRetryStrategy
secara default. Lihat bagian
Menyesuaikan percobaan ulang di bawah untuk mengetahui contoh cara mengubah
perilaku percobaan ulang default.
Node.js
Secara default, operasi mendukung percobaan ulang untuk kode error berikut ini:
- Error koneksi:
EAI_again
: Ini adalah error pencarian DNS. Informasi selengkapnya dapat ditemukan di sini.Connection reset by peer
: Ini berarti Google Cloud telah mereset koneksi.Unexpected connection closure
: Ini berarti Google Cloud telah menutup koneksi.
- Kode HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Semua setelan backoff eksponensial di library Node.js dapat dikonfigurasi. Secara default, operasi melalui Node.js menggunakan setelan berikut untuk backoff eksponensial:
Setelan | Nilai default (dalam detik) |
---|---|
Percobaan ulang otomatis | True jika idempoten |
Jumlah maksimum percobaan ulang | 3 |
Waktu tunggu awal | 1 detik |
Pengganda waktu tunggu per iterasi | 2 |
Jumlah waktu tunggu maksimum | 64 detik |
Batas waktu default | 600 detik |
Ada sebagian operasi Node.js yang idempoten bersyarat (aman untuk dicoba ulang dalam kondisi tertentu). Operasi tersebut hanya melakukan percobaan ulang jika menyertakan argumen tertentu:
ifGenerationMatch
ataugeneration
- Aman untuk dicoba ulang jika
ifGenerationMatch
ataugeneration
diteruskan sebagai opsi ke metode ini. Sering kali, metode hanya menerima salah satu dari dua parameter ini.
- Aman untuk dicoba ulang jika
ifMetagenerationMatch
- Aman untuk dicoba ulang jika
ifMetagenerationMatch
diteruskan sebagai opsi.
- Aman untuk dicoba ulang jika
retryOptions.idempotencyStrategy
ditetapkan ke
IdempotencyStrategy.RetryConditional
secara default. Lihat bagian
Menyesuaikan percobaan ulang di bawah untuk mengetahui contoh cara mengubah
perilaku percobaan ulang default.
PHP
Library klien PHP menggunakan backoff eksponensial secara default.
Python
Secara default, operasi mendukung percobaan ulang untuk kode error berikut ini:
- Error koneksi:
requests.exceptions.ConnectionError
requests.exceptions.ChunkedEncodingError
(hanya untuk operasi yang mengambil atau mengirim data payload ke objek, seperti upload dan download)ConnectionError
- Kode HTTP:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Operasi melalui Python menggunakan setelan default berikut untuk backoff eksponensial:
Setelan | Nilai default (dalam detik) |
---|---|
Percobaan ulang otomatis | True jika idempoten |
Waktu tunggu awal | 1 |
Pengganda waktu tunggu per iterasi | 2 |
Jumlah waktu tunggu maksimum | 60 |
Batas waktu default | 120 |
Ada sebagian operasi Python yang idempoten bersyarat (aman untuk dicoba ulang dalam kondisi tertentu) saat menyertakan argumen tertentu. Operasi tersebut hanya akan dicoba ulang jika kasus kondisi terpenuhi:
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
- Aman untuk dicoba ulang jika
generation
atauif_generation_match
diteruskan sebagai argumen ke metode. Sering kali metode hanya menerima salah satu dari dua parameter ini.
- Aman untuk dicoba ulang jika
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
- Aman untuk dicoba ulang jika
if_metageneration_match
diteruskan sebagai argumen ke metode.
- Aman untuk dicoba ulang jika
DEFAULT_RETRY_IF_ETAG_IN_JSON
- Aman untuk dicoba ulang jika metode menyisipkan
etag
ke dalam isi permintaan JSON. UntukHMACKeyMetadata.update()
, ini berarti ETag harus ditetapkan pada objekHMACKeyMetadata
itu sendiri. Untuk metodeset_iam_policy()
di kelas lain, ini berarti ETag harus ditetapkan dalam argumen "kebijakan" yang diteruskan ke metode.
- Aman untuk dicoba ulang jika metode menyisipkan
Ruby
Secara default, operasi mendukung percobaan ulang untuk kode error berikut ini:
- Error koneksi:
SocketError
HTTPClient::TimeoutError
Errno::ECONNREFUSED
HTTPClient::KeepAliveDisconnected
- Kode HTTP:
408 Request Timeout
429 Too Many Requests
5xx Server Error
Semua setelan backoff eksponensial di library klien Ruby dapat dikonfigurasi. Secara default, operasi melalui library klien Ruby menggunakan setelan berikut untuk backoff eksponensial:
Setelan | Nilai default |
---|---|
Percobaan ulang otomatis | Benar |
Jumlah maksimum percobaan ulang | 3 |
Waktu tunggu awal | 1 detik |
Pengganda waktu tunggu per iterasi | 2 |
Jumlah waktu tunggu maksimum | 60 detik |
Batas waktu default | 900 detik |
Ada sebagian operasi Ruby yang idempoten bersyarat (aman untuk dicoba ulang dalam kondisi tertentu) saat menyertakan argumen tertentu:
if_generation_match
ataugeneration
- Aman untuk dicoba ulang jika parameter
generation
atauif_generation_match
diteruskan sebagai argumen ke metode. Sering kali metode hanya menerima salah satu dari dua parameter ini.
- Aman untuk dicoba ulang jika parameter
if_metageneration_match
- Aman untuk dicoba ulang jika parameter
if_metageneration_match
diteruskan sebagai opsi.
- Aman untuk dicoba ulang jika parameter
Secara default, semua operasi idempoten dicoba ulang, dan operasi idempoten bersyarat dicoba ulang hanya jika kasus kondisi telah terpenuhi. Operasi non-idempoten tidak akan dicoba ulang. Lihat bagian Menyesuaikan percobaan ulang di bawah untuk mengetahui contoh cara mengubah perilaku percobaan ulang default.
REST API
Saat memanggil JSON atau XML API secara langsung, Anda harus menggunakan algoritma backoff eksponensial untuk mengimplementasikan strategi percobaan ulang Anda sendiri.
Menyesuaikan percobaan ulang
Konsol
Anda tidak dapat menyesuaikan perilaku percobaan ulang menggunakan Konsol Google Cloud.
Command line
Untuk perintah gcloud storage
, Anda dapat mengontrol strategi percobaan ulang dengan
membuat konfigurasi bernama dan menetapkan beberapa atau semua
properti berikut ini:
base_retry_delay
exponential_sleep_multiplier
max_retries
max_retry_delay
Anda kemudian menerapkan konfigurasi yang ditentukan per perintah menggunakan flag --configuration
di seluruh project atau untuk semua perintah gcloud menggunakan perintah gcloud config set
.
Untuk gsutil, Anda dapat mengonfigurasi jumlah percobaan ulang dan penundaan maksimum setiap percobaan ulang dengan mengedit variabel konfigurasi num_retries
dan max_retry_delay
di bagian "[Boto]"
dari file konfigurasi .boto
.
Library klien
C++
Untuk menyesuaikan perilaku percobaan ulang, berikan nilai untuk opsi berikut
saat Anda melakukan inisialisasi objek google::cloud::storage::Client
:
google::cloud::storage::RetryPolicyOption
: Library ini menyediakan kelasgoogle::cloud::storage::LimitedErrorCountRetryPolicy
dangoogle::cloud::storage::LimitedTimeRetryPolicy
. Anda dapat menyediakan kelas Anda sendiri, yang harus mengimplementasikan antarmukagoogle::cloud::RetryPolicy
.google::cloud::storage::BackoffPolicyOption
: Library ini menyediakan kelasgoogle::cloud::storage::ExponentialBackoffPolicy
. Anda dapat menyediakan kelas Anda sendiri, yang harus mengimplementasikan antarmukagoogle::cloud::storage::BackoffPolicy
.google::cloud::storage::IdempotencyPolicyOption
: Library ini menyediakan kelasgoogle::cloud::storage::StrictIdempotencyPolicy
dangoogle::cloud::storage::AlwaysRetryIdempotencyPolicy
. Anda dapat menyediakan kelas Anda sendiri, yang harus mengimplementasikan antarmukagoogle::cloud::storage::IdempotencyPolicy
.
Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi library klien C++.
C#
Saat ini, Anda tidak dapat menyesuaikan strategi percobaan ulang default yang digunakan oleh library klien C#.
Go
Saat Anda melakukan inisialisasi klien penyimpanan, konfigurasi percobaan ulang default akan ditetapkan. Kecuali jika diabaikan, opsi dalam konfigurasi tersebut akan ditetapkan ke nilai default. Pengguna dapat mengonfigurasi perilaku percobaan ulang non-default untuk satu panggilan library (menggunakan BucketHandle.Retryer dan ObjectHandle.Retryer) atau untuk semua panggilan yang dibuat oleh klien (menggunakan Client.SetRetry). Untuk mengubah perilaku percobaan ulang, teruskan RetryOptions yang diinginkan ke salah satu metode ini.
Lihat contoh kode berikut untuk mempelajari cara menyesuaikan perilaku percobaan ulang.
Java
Saat Anda melakukan inisialisasi Storage
, instance
RetrySettings
juga akan diinisialisasi. Kecuali jika
diabaikan, opsi di RetrySettings
akan ditetapkan ke nilai default.
Untuk mengubah perilaku percobaan ulang otomatis default, teruskan
StorageRetryStrategy
kustom ke StorageOptions
yang digunakan untuk membuat
instance Storage
. Untuk memodifikasi salah satu parameter skalar lainnya, teruskan
RetrySettings
kustom ke StorageOptions
yang digunakan untuk membuat
instance Storage
.
Lihat contoh berikut untuk mempelajari cara menyesuaikan perilaku percobaan ulang Anda:
Node.js
Saat Anda menginisialisasi Cloud Storage, file konfigurasi retryOptions juga akan diinisialisasi. Kecuali jika diabaikan, opsi dalam konfigurasi tersebut akan ditetapkan ke nilai default. Untuk mengubah perilaku percobaan ulang default, teruskan konfigurasi percobaan ulang kustom retryOptions
ke dalam konstruktor penyimpanan saat inisialisasi.
Library klien Node.js dapat otomatis menggunakan strategi backoff untuk mencoba ulang permintaan dengan parameter autoRetry
.
Lihat contoh kode berikut untuk mempelajari cara menyesuaikan perilaku percobaan ulang.
PHP
Saat ini, Anda tidak dapat menyesuaikan strategi percobaan ulang default yang digunakan oleh library klien PHP.
Python
Untuk mengubah perilaku percobaan ulang default, buat salinan
objek google.cloud.storage.retry.DEFAULT_RETRY
dengan memanggilnya menggunakan
metode with_XXX
. Library klien Python otomatis menggunakan strategi backoff untuk mencoba ulang permintaan jika Anda menyertakan parameter DEFAULT_RETRY
.
Perlu diperhatikan bahwa with_predicate
tidak didukung untuk operasi yang mengambil atau mengirim data payload ke objek, seperti upload dan download. Sebaiknya Anda memodifikasi atribut satu per satu. Untuk mengetahui informasi selengkapnya,
lihat Referensi Percobaan Ulang google-api-core.
Untuk mengonfigurasi percobaan ulang bersyarat Anda sendiri, buat objek ConditionalRetryPolicy
dan gabungkan objek Retry
kustom Anda dengan DEFAULT_RETRY_IF_GENERATION_SPECIFIED
, DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
, atau
DEFAULT_RETRY_IF_ETAG_IN_JSON
.
Lihat contoh kode berikut untuk mempelajari cara menyesuaikan perilaku percobaan ulang.
Ruby
Saat Anda melakukan inisialisasi klien penyimpanan, semua konfigurasi percobaan ulang akan ditetapkan ke nilai yang ditampilkan pada tabel di atas. Untuk mengubah perilaku percobaan ulang default, teruskan konfigurasi percobaan ulang saat melakukan inisialisasi klien penyimpanan.
Untuk mengganti jumlah percobaan ulang untuk operasi tertentu, teruskan retries
dalam parameter options
operasi.
REST API
Gunakan algotitma backoff eksponensial untuk mengimplementasikan strategi percobaan ulang Anda sendiri.
Algotitma backoff eksponensial
Algotitma backoff eksponensial mencoba ulang permintaan menggunakan waktu tunggu yang meningkat secara eksponensial di antara permintaan, hingga waktu backoff maksimum. Biasanya Anda harus menggunakan backoff eksponensial dengan jitter untuk mencoba ulang permintaan yang memenuhi kriteria respons dan idempotensi. Untuk praktik terbaik dalam mengimplementasikan percobaan ulang otomatis dengan backoff eksponensial, lihat Mengatasi Kegagalan Beruntun.
Langkah berikutnya
- Pelajari cara mencoba ulang permintaan di Storage Transfer Service dengan Java atau Python.
- Pelajari prasyarat permintaan lebih lanjut.