Halaman ini menjelaskan praktik terbaik untuk menjalankan dan mengelola operasi berjalan lama (LROs) di Cloud Healthcare API. Untuk ringkasan LRO di Cloud Healthcare API, lihat Mengelola operasi yang berjalan lama.
Properti LRO
Bagian berikut berlaku untuk metode yang tercantum di Metode yang menampilkan LRO.
Dampak kuota
LRO tidak berbagi kuota dengan metode create, read, update, dan delete (CRUD) Cloud Healthcare API yang menggunakan jenis kuota berikut:
Kuota LRO dihitung menggunakan metrik fhir_store_lro_ops
dan dicom_store_lro_ops
.
Cloud Healthcare API membatasi jumlah LRO yang dapat berjalan secara serentak dalam project Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Batas jumlah LRO.
Throughput data
Metode LRO biasanya mencapai throughput data yang lebih tinggi daripada
metode CRUD yang setara. Misalnya, mengimpor instance DICOM dengan dicomStores.import
biasanya lebih baik daripada menyimpan instance satu per satu dengan dicomStores.storeInstances
.
Menjalankan beberapa LRO secara serentak mungkin tidak meningkatkan throughput data karena batasan berikut, terutama saat memproses volume data yang besar:
- Batasan kuota
- Pertentangan resource
- Traffic lain yang dikirim project Google Cloud Anda ke Cloud Healthcare API saat LRO berjalan
Untuk throughput data maksimum saat menjalankan LRO, pertimbangkan hal berikut:
- Batch impor dan ekspor kecil biasanya memiliki throughput yang rendah karena overhead.
- LRO berjalan dan menggunakan kuota secara terpisah dari operasi Cloud Healthcare API lainnya.
- Setiap LRO memiliki throughput maksimum.
- LRO serentak pada resource yang sama dapat menyebabkan pertentangan kunci.
- Cloud Healthcare API membatasi jumlah LRO yang dapat berjalan secara serentak dalam project Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Batas jumlah LRO.
Rencanakan jumlah LRO yang diperlukan kasus penggunaan Anda. Jika Anda harus mempartisi batch data besar di beberapa LRO, usahakan jumlah partisi tetap rendah.
Integritas referensial FHIR
Metode fhirStores.import
tidak mempertimbangkan
setelan
disableReferentialIntegrity
. Hal ini memungkinkan Anda mengimpor data dengan dependensi arbitrer yang tidak
memerlukan pengurutan atau pengelompokan, yang meningkatkan throughput data. Jika data input
berisi referensi yang tidak valid atau jika beberapa resource FHIR gagal diimpor, status penyimpanan
FHIR mungkin melanggar
integritas referensi.
Untuk menggunakan fhirStores.import
, aplikasi klien Anda harus
memastikan referensi resource FHIR valid dengan memverifikasi hal berikut:
- Data dan format resource FHIR sudah benar
- Semua error yang terjadi selama impor akan dikelola
Untuk menerapkan integritas referensial, gunakan fhir.create
atau fhir.executeBundle
,
bukan fhirStores.import
. Untuk informasi
selengkapnya, lihat Mengimpor data FHIR versus menjalankan paket.
Notifikasi Pub/Sub
Beberapa metode Cloud Healthcare API mengirim notifikasi Pub/Sub untuk peristiwa klinik, seperti pembuatan atau penghapusan resource layanan kesehatan. Untuk mengetahui daftar metode yang mengirim notifikasi Pub/Sub, lihat Mengonfigurasi notifikasi Pub/Sub.
Metode impor berikut tidak mengirim notifikasi Pub/Sub:
Jika bagian aplikasi Anda memerlukan notifikasi saat impor selesai, gunakan metode notifikasi lain yang dapat mencantumkan data dalam impor.
Batas penanganan error
Cloud Healthcare API mungkin tidak mencatat semua error dalam LRO, terutama jika LRO memproses volume data yang besar dan menghasilkan banyak error. Terapkan cara untuk melacak pemrosesan dan error LRO secara terpisah. Untuk mengetahui informasi selengkapnya, lihat Penanganan error resource.
Pengindeksan data dan penelusuran
Penundaan pada hasil penelusuran dapat terjadi karena pengindeksan penelusuran asinkron. Jika LRO membuat atau memperbarui resource FHIR, mungkin perlu waktu tambahan sebelum perubahan tersedia di hasil penelusuran.
Misalnya, penelusuran resource Pasien di penyimpanan FHIR mungkin tidak langsung menampilkan semua hasil setelah operasi impor FHIR.
Urutan eksekusi
LRO dijadwalkan berdasarkan ketersediaan resource Google Cloud. Urutan eksekusi dan penyelesaian LRO mungkin tidak cocok dengan urutan permintaannya.
Menghindari permintaan impor dan ekspor kecil
Bagian ini menjelaskan batasan LRO saat memproses volume data kecil.
LRO yang ditampilkan dari operasi impor dan ekspor membantu menskalakan throughput data dengan memproses data dalam jumlah besar dengan cepat dan menghindari lonjakan beban. Untuk menyimpan data dalam jumlah kecil, gunakan teknik lain di Praktik terbaik untuk menyimpan data.
Batasan jumlah LRO
Cloud Healthcare API membatasi jumlah LRO yang dapat berjalan secara serentak dalam project Google Cloud. Batas ini didasarkan pada hal berikut:
- Jenis LRO.
- Jumlah resource Google Cloud yang dialokasikan ke LRO. Hal ini didasarkan pada ukuran data input.
Jika Anda menjalankan terlalu banyak LRO, Cloud Healthcare API akan membatasi kapasitas, menghasilkan error, dan dapat mengurangi throughput LRO. Cloud Healthcare API secara otomatis menghemat resource Google Cloud sehingga jumlah LRO tetap dalam batas resource.
LRO adalah proses latar belakang, sehingga jika beban dari LRO mengganggu proses dengan prioritas lebih tinggi, seperti operasi CRUD, Cloud Healthcare API dapat mengurangi throughput LRO. Hal ini memastikan bahwa proses dengan prioritas lebih tinggi tersedia.
Overhead pembersihan dan alokasi resource
Saat LRO dimulai, Cloud Healthcare API akan mengalokasikan resource. Proses ini dapat memerlukan waktu beberapa menit karena Cloud Healthcare API harus melakukan hal berikut:
- Memulai proses pengontrol.
- Mengalokasikan pekerja dari kumpulan pekerja.
- Tentukan ukuran data input.
- Mulai alokasikan pekerjaan dalam skala besar.
Menghentikan dan membersihkan LRO juga dapat memerlukan waktu beberapa menit.
Karena overhead, LRO yang memproses sejumlah kecil data mungkin menghabiskan sebagian besar waktunya untuk mengalokasikan kumpulan pekerja dan membersihkan resource.
Jika memiliki banyak LRO ini, Anda mungkin mengalami throughput data yang lebih rendah karena kemungkinan besar Anda memenuhi batas kuota project Google Cloud.
Batasan untuk meminta kuota LRO
Sebelum meminta kuota LRO lebih banyak, terapkan Praktik terbaik untuk pengelolaan kuota. Jika Anda masih memerlukan kuota lebih banyak, hubungi Cloud Customer Care Google. Untuk membuat permintaan, lihat Praktik terbaik untuk meminta kuota tambahan.
Anda mungkin memerlukan kuota tambahan jika data input Anda besar, misalnya:
- Anda mengimpor instance DICOM yang berukuran beberapa petabyte (PB).
- Anda mengimpor puluhan miliar resource FHIR.
Status LRO dan status kegagalan
Saat Anda memulai LRO, responsnya akan berisi ID unik. Anda dapat melihat status LRO dengan melakukan polling ID-nya. Setelah selesai, LRO memiliki salah satu status berikut:
- Berhasil selesai tanpa error
- Berhasil selesai dengan beberapa error
- Gagal selesai, tetapi mungkin menghasilkan output sebagian sebelum gagal
Contoh JSON berikut menjelaskan respons yang ditampilkan saat LRO selesai:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "METADATA_TYPE", "apiMethodName": "API_METHOD_NAME", "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ", "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ", "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL" "counter": { "success": "SUCCESS_COUNT", // If there were any failures, they display in the `failure` field. "failure": "FAILURE_COUNT" } }, "done": true, // The `response` field only displays if there were no errors. "response": { "@type": }, // If there were any errors, an `error` field displays instead of a `response` field. // See Troubleshooting long-running operations for a list of response codes. "error": { "code": ERROR_CODE, "message": "DESCRIPTION", "details": [ { "@type": "...", FIELD1: ..., ... } ] } }
Untuk mendapatkan status LRO, mencantumkan LRO, dan membatalkan LRO, lihat Mengelola operasi yang berjalan lama.
Mengelola status LRO dan status kegagalan
Untuk mengelola status LRO dan status kegagalan, ikuti praktik terbaik berikut:
- Mengambil sampel LRO untuk mendapatkan statusnya dan memverifikasi kapan LRO selesai. Untuk melakukan polling pada LRO, panggil metode
projects.locations.datasets.operations.get
berulang kali hingga operasi selesai. Gunakan backoff di antara setiap permintaan polling, seperti 10 detik. Jika respons berisi"done": true
, LRO telah selesai. Setelah LRO selesai, periksa apakah respons berisi kolom
error
. Jika ya, tentukan apakah akan mencoba kembali operasi berdasarkan hal berikut:- Kode error. Lihat Memecahkan masalah LRO untuk mengetahui kode error dan tindakan yang direkomendasikan.
- Jumlah percobaan ulang yang sudah terjadi.
- Waktu antara saat LRO dimulai dan saat error terjadi. Misalnya, jika LRO yang biasanya memerlukan waktu beberapa jam memerlukan waktu beberapa hari dan belum menampilkan status kegagalan, Anda mungkin ingin manusia melakukan intervensi. Untuk mengetahui informasi selengkapnya tentang kapan intervensi manusia mungkin diperlukan, lihat Merencanakan status error akhir.
Lihat Menempatkan LRO dalam antrean untuk mengetahui informasi tentang cara mencoba ulang LRO.
Jika Anda tidak mencoba lagi LRO, lihat kolom
metadata.counter.failure
untuk melihat apakah error terjadi pada resource tertentu. Anda mungkin dapat memproses resource satu per satu. Untuk mengetahui informasi selengkapnya, lihat Menangani error resource.
Menangani error resource
LRO dapat selesai dengan error. Error dalam respons LRO mengikuti model error Google Cloud. Respons LRO menyertakan link ke Cloud Logging untuk informasi selengkapnya.
Detail error LRO
Error LRO di Cloud Logging memiliki properti berikut:
Log error Cloud Logging tidak berisi ID LRO. Gunakan kolom
operation.id
danoperation.producer
untuk menemukan status dan error LRO. Misalnya, LRO yang dipanggil dari metodeprojects.locations.datasets.fhirStores.import
berisiimport_fhir
di kolomoperation.producer
.Jika beberapa LRO memiliki
operation.id
danoperation.producer
yang sama, gunakan stempel waktucreateTime
danendTime
untuk mengidentifikasi LRO yang benar.Tidak semua error LRO tersedia di Cloud Logging. Kolom
metadata.counter.failure
mungkin melebihi jumlah error sebenarnya yang dicatat ke dalam log karena hal berikut:- Batasan kuota Cloud Logging
- Ketersediaan layanan Cloud Logging
- Batas log LRO
Misalnya, jika LRO mengimpor 10 juta resource FHIR, dan 50% di antaranya memiliki error pemformatan, hanya beberapa ratus atau beberapa ribu error yang mungkin dicatat ke dalam log karena pembatasan kapasitas dan kuota Cloud Logging.
Jumlah error yang dicatat ke dalam log juga bervariasi, bergantung pada durasi LRO berjalan saat mengalami tingkat error tinggi. Jika berjalan lambat, LRO mungkin menampilkan lebih banyak error di Cloud Logging karena error tersebar selama waktu yang lama dan tidak tunduk pada pembatasan kapasitas.
Efek mencoba ulang LRO
Jika LRO mengalami error dan aplikasi klien otomatis mencoba ulang operasi menggunakan data yang sama, percobaan ulang tersebut dapat menyebabkan lebih banyak error.
Pertimbangkan skenario saat LRO fhirStores.import
selesai dengan error
karena beberapa resource FHIR yang dicoba diimpor tidak valid.
Mencoba ulang impor secara otomatis dengan data yang sama dapat menghasilkan banyak error 409 ALREADY_EXISTS
karena beberapa resource FHIR diimpor dalam operasi asli. Jika Anda membuat kueri LRO dan menemukan operasi pembuatan yang gagal, jangan coba lagi secara otomatis. Manusia harus meninjau
error 409 ALREADY_EXISTS
.
Jika percobaan ulang berhasil, kolom metadata.counter.failure
tidak akan menyertakan error dari operasi sebelumnya. Hal ini dapat menyebabkan jumlah error yang salah karena respons dari percobaan ulang yang berhasil tidak menyertakan error dari upaya sebelumnya.
Mencoba lagi LRO
Jika Anda memiliki pipeline pemrosesan sisi klien yang mendeteksi error LRO, jangan gunakan Cloud Logging. Seperti yang ditunjukkan dalam Detail error LRO, log error Cloud Logging untuk LRO tidak dapat diandalkan dan tidak lengkap. Sebagai gantinya, gunakan teknik di bagian berikut.
Mencoba lagi operasi impor
Untuk mendeteksi data yang gagal diimpor, bandingkan data yang diimpor di Cloud Healthcare API dengan data sumbernya di Cloud Storage. Anda dapat mengimpor data menggunakan metode berikut:
projects.locations.datasets.fhirStores.import
projects.locations.datasets.dicomStores.import
projects.locations.datasets.hl7V2Stores.import
Gunakan ID unik, seperti nomor rekam medis (MRN) untuk resource FHIR Patient, untuk membandingkan data.
Lihat Efek mencoba ulang LRO untuk mengetahui langkah-langkah yang harus dilakukan saat mencoba ulang operasi impor.
Menjalankan ulang impor dapat membuat ulang resource yang sebelumnya Anda hapus. Pertimbangkan skenario berikut:
- Anda mencoba mengimpor 1.000.000 resource FHIR. 50.000 resource gagal karena error pemformatan.
- Anda menghabiskan beberapa hari untuk memperbaiki error pemformatan. Selama waktu tersebut, seorang pasien meminta Anda untuk menghapus datanya.
- Jika Anda menjalankan kembali impor, Anda berisiko membuat ulang data pasien yang telah Anda hapus.
Mencoba kembali operasi ekspor
Untuk mendeteksi data yang gagal diekspor ke BigQuery, tulis skrip untuk membandingkan ID unik dalam data sumber dengan data yang diekspor.
Anda dapat mengekspor data ke BigQuery menggunakan metode berikut:
projects.locations.datasets.fhirStores.export
projects.locations.datasets.dicomStores.export
projects.locations.datasets.hl7V2Stores.export
Mengantrekan dan mengelola LRO
Jika Anda menjalankan LRO yang memproses volume data besar untuk orientasi atau sesuai jadwal reguler, terapkan teknik antrean LRO berikut:
- Batasi LRO serentak menjadi jumlah kecil, seperti
5
. Anda dapat menyesuaikan batas ini bergantung pada ukuran dan jenis LRO yang dijalankan. - Memantau penyelesaian LRO. Jika terjadi error, jadwalkan ulang LRO atau selesaikan error secara terpisah di pipeline pemrosesan Anda.
Atasi error secara otomatis di Menangani error resource jika memungkinkan.
Pahami kasus penggunaan untuk impor FHIR guna menentukan apakah akan mengabaikan error
409 ALREADY_EXISTS
atau melakukan operasi CRUD terpisah untuk mengatasi error tersebut. Seperti yang ditunjukkan dalam detail error LRO, beberapa error409 ALREADY_EXISTS
mungkin tidak dicatat ke Cloud Logging. Jika aplikasi Anda mengandalkan log error, gunakan salah satu teknik di Mencoba lagi LRO.Untuk mengatasi beberapa error, antrekan LRO yang lebih kecil untuk data yang mengalami error atau lakukan operasi CRUD terpisah.
Untuk mengatasi banyak error, menjalankan ulang LRO mungkin merupakan opsi paling sederhana untuk memastikan konsistensi. Lihat Mencoba kembali operasi impor untuk mengetahui risiko menjalankan kembali impor pada data yang dihapus.
Mendeteksi secara otomatis apakah intervensi manusia diperlukan untuk mengatasi error. Anda harus memiliki alat dan playbook operasional untuk administrator sistem. Tugas untuk mengatasi error dapat mencakup hal berikut:
- Menjadwalkan ulang LRO.
- Menjadwalkan ulang sebagian data dari LRO sebelumnya.
- Periksa error dan tangani setiap elemen data yang mengalami error. Tugas ini hanya dapat dilakukan jika Anda dapat menentukan bahwa semua error di LRO dicatat ke dalam log.
Menentukan jadwal LRO. Anda dapat menjadwalkan LRO agar tidak berjalan pada jam sibuk saat banyak operasi CRUD berjalan. Untuk mengetahui informasi selengkapnya, lihat Mengelola kuota untuk memaksimalkan throughput data.
Memantau dan menerima pemberitahuan
Buat dan pertahankan prosedur untuk memantau LRO dan menyelesaikan pemberitahuan. Notifikasi secara utama disebabkan oleh status LRO dan masalah antrean. Prosedur harus menangani situasi berikut:
- LRO yang gagal mencoba ulang lebih dari yang dikonfigurasi.
- Masalah yang memerlukan intervensi manusia untuk menyelesaikan sebagian error. Misalnya, jika LRO gagal, dan klien tidak dapat menyelesaikan error, intervensi manusia mungkin diperlukan. Lihat Antrean dan mengelola LRO untuk mengetahui informasi selengkapnya tentang cara menyelesaikan masalah yang memerlukan intervensi manusia.
- Antrean yang melebihi panjang atau tumbuh terlalu cepat.
- Persyaratan kebijakan tidak terpenuhi, seperti masalah izin atau kesalahan konfigurasi.
- Pemeriksaan konsistensi yang menunjukkan masalah sistemis di beberapa LRO. Anda mungkin memiliki beberapa LRO de-identifikasi yang mengharapkan set data sumber dan set data tujuan memiliki jumlah resource FHIR yang sama. Jika ada perbedaan yang semakin besar dari waktu ke waktu, hal ini mungkin menunjukkan data yang belum diproses.
- Masalah kuota LRO. Untuk informasi selengkapnya, lihat Mengelola kuota untuk memaksimalkan throughput data dan Praktik terbaik untuk pengelolaan kuota.