Praktik terbaik operasi yang berjalan lama

Halaman ini menjelaskan praktik terbaik untuk menjalankan dan mengelola operasi yang berjalan lama (LRO) 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 dalam Metode yang menampilkan LRO.

Dampak kuota

LRO tidak berbagi kuota dengan metode create, read, update, dan delete (CRUD) Cloud Healthcare API yang memakai 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 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 akan berperforma lebih baik daripada penyimpanan instance satu per satu dengan dicomStores.storeInstances.

Menjalankan beberapa LRO secara bersamaan mungkin tidak meningkatkan throughput data karena batasan berikut, terutama saat memproses volume data yang besar:

Pembatasan 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 informasi selengkapnya, lihat Batas jumlah LRO.

Rencanakan jumlah LRO yang diperlukan kasus penggunaan Anda. Jika Anda harus mempartisi batch data yang besar di beberapa LRO, cobalah untuk mengurangi jumlah partisi.

Integritas referensial FHIR

Metode fhirStores.import tidak mempertimbangkan setelan disableReferentialIntegrity. Hal ini memungkinkan Anda mengimpor data dengan interdependensi arbitrer yang tidak memerlukan pengurutan atau pengelompokan, sehingga meningkatkan throughput data. Jika data input berisi referensi yang tidak valid atau jika beberapa resource FHIR gagal diimpor, status penyimpanan FHIR mungkin melanggar integritas referensial.

Untuk menggunakan fhirStores.import, aplikasi klien Anda harus memastikan referensi resource FHIR valid dengan memverifikasi hal berikut:

Format dan data resource FHIR sudah benar
Setiap error yang terjadi selama proses impor akan dikelola

Untuk menerapkan integritas referensial, gunakan fhir.create atau fhir.executeBundle, bukan fhirStores.import. Untuk mengetahui informasi selengkapnya, lihat Mengimpor data FHIR versus menjalankan paket.

Notifikasi Pub/Sub

Beberapa metode Cloud Healthcare API mengirimkan notifikasi Pub/Sub untuk peristiwa klinik, seperti pembuatan atau penghapusan resource layanan kesehatan. Untuk daftar metode yang mengirim notifikasi Pub/Sub, lihat Mengonfigurasi notifikasi Pub/Sub.

Metode impor berikut tidak mengirimkan notifikasi Pub/Sub:

Jika bagian dari 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 hasil penelusuran dapat terjadi karena pengindeksan penelusuran asinkron. Jika LRO membuat atau memperbarui resource FHIR, mungkin diperlukan waktu tambahan sebelum perubahan tersedia di hasil penelusuran.

Misalnya, penelusuran untuk 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 LRO yang dieksekusi dan diselesaikan mungkin tidak cocok dengan urutan saat LRO diminta.

Menghindari permintaan impor dan ekspor dalam jumlah 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 secara cepat dan menghindari lonjakan beban. Untuk menyimpan data dalam jumlah kecil, gunakan teknik lain dalam Praktik terbaik untuk menyimpan data.

Batasan jumlah LRO

Cloud Healthcare API membatasi jumlah LRO yang dapat berjalan secara serentak dalam project Google Cloud. Batas tersebut 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 otomatis menghemat resource Google Cloud sehingga jumlah LRO tetap dalam batas resource.

LRO adalah proses di latar belakang, sehingga jika beban dari LRO mengganggu proses dengan prioritas yang lebih tinggi, operasi CRUD tersebut, Cloud Healthcare API dapat mengurangi throughput LRO. Hal ini memastikan bahwa proses dengan prioritas yang lebih tinggi tersedia.

Overhead pembersihan dan alokasi resource

Saat LRO dimulai, Cloud Healthcare API mengalokasikan resource. Proses ini dapat memerlukan waktu beberapa menit karena Cloud Healthcare API harus melakukan hal berikut:

Mulai proses pengontrol.
Mengalokasikan pekerja dari kumpulan pekerja.
Tentukan ukuran data input.
Mulai mengalokasikan pekerjaan dalam skala besar.

Menghentikan dan membersihkan LRO juga dapat memerlukan waktu beberapa menit.

Karena adanya overhead, LRO yang memproses data dalam jumlah kecil mungkin menghabiskan sebagian besar waktunya untuk mengalokasikan kumpulan pekerja dan membersihkan resource.

Jika memiliki banyak LRO ini, Anda mungkin akan mendapati throughput data yang lebih rendah karena kemungkinan besar Anda akan memenuhi batas kuota project Google Cloud.

Batasan permintaan kuota LRO

Sebelum meminta lebih banyak kuota LRO, terapkan Praktik terbaik untuk pengelolaan kuota. Jika Anda masih memerlukan kuota lebih banyak, hubungi Google Cloud Customer Care. 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, respons akan berisi ID unik. Anda dapat melihat status LRO dengan melakukan polling ID-nya. Setelah LRO selesai, LRO memiliki salah satu status berikut:

Berhasil diselesaikan tanpa error
Berhasil menyelesaikan dengan beberapa error
Gagal diselesaikan, 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:

Lakukan polling LRO untuk mengetahui statusnya dan verifikasi saat LRO sudah selesai. Untuk melakukan polling 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 kode error dan tindakan yang disarankan.
- Jumlah percobaan ulang yang telah 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 meminta campur tangan manusia. Untuk mengetahui informasi selengkapnya tentang kapan intervensi manual mungkin diperlukan, lihat Merencanakan status error akhir.
Lihat Mengantrekan LRO untuk mengetahui informasi tentang cara mencoba kembali LRO.
Jika Anda tidak mencoba kembali LRO, lihat kolom metadata.counter.failure untuk melihat apakah terjadi error pada resource tertentu. Anda mungkin dapat memproses resource satu per satu. Untuk mengetahui informasi selengkapnya, lihat Menangani error resource.

Menangani error resource

LRO dapat diselesaikan dengan error. Error dalam respons LRO mengikuti model error Google Cloud. Respons LRO menyertakan link ke Cloud Logging untuk mengetahui 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 dan operation.producer untuk menemukan status dan error LRO. Misalnya, LRO yang dipanggil dari metode projects.locations.datasets.fhirStores.import berisi import_fhir di kolom operation.producer.

Jika beberapa LRO memiliki operation.id dan operation.producer yang sama, gunakan stempel waktu createTime dan endTime 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 karena pembatasan kapasitas dan kuota Cloud Logging.

Jumlah error yang dicatat ke dalam log juga bervariasi bergantung pada berapa lama LRO berjalan dan tingkat error-nya tinggi. Jika LRO berjalan lambat, error mungkin akan muncul di Cloud Logging karena error tersebut menyebar dalam waktu yang lama dan tidak dikenai pembatasan kapasitas.

Efek dari percobaan ulang LRO

Jika LRO mengalami error dan aplikasi klien otomatis mencoba ulang operasi menggunakan data yang sama, percobaan ulang mungkin akan menyebabkan lebih banyak error.

Pertimbangkan skenario saat LRO fhirStores.import diakhiri dengan error karena beberapa resource FHIR yang dicoba diimpor tidak valid. Mencoba kembali 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 mencoba lagi secara otomatis. Seorang 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 mencakup error dari upaya sebelumnya.

Mencoba kembali LRO

Jika Anda memiliki pipeline pemrosesan sisi klien yang mendeteksi error LRO, jangan gunakan Cloud Logging. Seperti 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 kembali 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:

Gunakan ID unik, seperti nomor rekam medis (MRN) untuk resource Pasien FHIR, untuk membandingkan data.

Lihat Efek dari percobaan ulang LRO untuk mengetahui langkah-langkah yang harus dilakukan saat mencoba kembali operasi impor.

Menjalankan kembali impor dapat membuat ulang resource yang sebelumnya Anda hapus. Pertimbangkan skenario berikut:

Coba impor 1.000.000 resource FHIR. 50.000 resource gagal karena error format.
Anda perlu waktu beberapa hari untuk memperbaiki error format. Selama waktu itu, seorang pasien meminta Anda untuk menghapus catatan mereka.
Jika impor ulang dijalankan, Anda berisiko membuat ulang data pasien yang telah dihapus.

Mencoba lagi 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:

Mengantrekan dan mengelola LRO

Jika Anda menjalankan LRO yang memproses volume data besar untuk orientasi atau secara rutin, terapkan teknik antrean LRO berikut:

Batasi LRO serentak ke angka kecil, seperti 5. Anda dapat menyesuaikan batas ini, bergantung pada ukuran dan jenis LRO yang dijalankan.
Pantau penyelesaian LRO. Jika terjadi error, jadwalkan ulang LRO atau atasi error secara terpisah di pipeline pemrosesan Anda.
Otomatis atasi error di Menangani error resource jika memungkinkan.
- Pahami kasus penggunaan 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 error 409 ALREADY_EXISTS mungkin tidak dicatat ke Cloud Logging. Jika aplikasi Anda mengandalkan log error, gunakan salah satu teknik dalam Mencoba kembali 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 kembali LRO mungkin merupakan opsi paling sederhana untuk memastikan konsistensi. Lihat Mencoba kembali operasi impor untuk mengetahui risiko menjalankan kembali impor pada data yang dihapus.
Otomatis mendeteksi apakah intervensi manual diperlukan untuk mengatasi error. Anda seharusnya memiliki alat dan playbook operasional untuk administrator sistem. Tugas untuk mengatasi error dapat mencakup hal berikut:
- Jadwalkan ulang LRO.
- Menjadwalkan ulang subset data dari LRO sebelumnya.
- Memeriksa {i>error<i} dan menangani elemen data individual yang mengalami {i>error<i}. Tugas ini hanya dapat dilakukan jika Anda dapat memastikan bahwa semua error dalam LRO telah dicatat ke dalam log.
Menentukan jadwal LRO. Anda dapat menjadwalkan LRO agar tidak berjalan pada jam sibuk ketika banyak operasi CRUD sedang berjalan. Untuk mengetahui informasi selengkapnya, lihat Mengelola kuota untuk memaksimalkan throughput data.

Memantau dan menerima pemberitahuan

Membuat dan memelihara prosedur untuk memantau LRO dan menyelesaikan pemberitahuan. Pemberitahuan utamanya disebabkan oleh status LRO dan masalah queueing. Prosedur harus menangani situasi berikut:

LRO yang gagal mencoba ulang lebih dari jumlah yang dikonfigurasi.
Masalah yang memerlukan campur tangan manusia untuk menyelesaikan sebagian error. Misalnya, jika LRO gagal, dan klien tidak dapat mengatasi error, intervensi manual mungkin diperlukan. Lihat Mengantrekan dan mengelola LRO untuk mengetahui informasi selengkapnya tentang cara menyelesaikan masalah yang memerlukan campur tangan manusia.
Antrean yang melebihi panjang atau bertambah terlalu cepat.
Persyaratan kebijakan tidak terpenuhi, seperti masalah izin atau kesalahan konfigurasi.
Pemeriksaan konsistensi yang menunjukkan masalah sistemik 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 meningkat seiring waktu, hal ini mungkin menunjukkan data yang belum diproses.
Masalah kuota LRO. Untuk mengetahui informasi selengkapnya, lihat artikel Mengelola kuota untuk memaksimalkan throughput data dan Praktik terbaik untuk pengelolaan kuota.