View a markdown version of this page

Menambal sumber daya dalam skala besar dengan $bulk-patch - AWS HealthLake
PenggunaanParameterMenargetkan sumber dayaFormat patch yang didukungMulai contoh pekerjaan patch massalPolling status pekerjaan patch massalAlasan umum yang dilewatiKegagalan pelanggan umumPraktik terbaikOtorisasiKarakteristik kinerjaOperasi terkait

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menambal sumber daya dalam skala besar dengan $bulk-patch

AWS HealthLake mendukung $bulk-patch operasi untuk menerapkan operasi patch ke sejumlah besar sumber daya FHIR secara asinkron. Anda dapat menargetkan daftar sumber daya tertentu berdasarkan ID, atau semua sumber daya dari jenis tertentu dalam datastore. Dengan operasi ini, Anda dapat memodifikasi sumber daya dalam skala besar tanpa memperbarui setiap sumber daya secara individual.

$bulk-patchOperasi ini sangat berguna ketika Anda perlu melakukan hal berikut:

  • Menerapkan tag atau label metadata ke sumber daya di seluruh penyimpanan data

  • Perbarui bidang tertentu pada ribuan atau jutaan sumber daya

  • Melakukan koreksi atau pengayaan data massal

  • Menerapkan perubahan terkait kepatuhan di seluruh jenis sumber daya

  • Migrasi atau standarisasi elemen data dalam skala besar

catatan

  • $bulk-patchOperasi menerapkan patch yang sama untuk setiap sumber daya yang ditargetkan. Untuk memodifikasi sumber daya individu, gunakan operasi PATCH. Untuk informasi selengkapnya, lihat Memodifikasi Sumber Daya dengan Operasi PATCH.

  • Patch massal menerapkan setiap patch secara atomik ke setiap sumber daya. Setiap sumber daya berhasil atau gagal secara independen.

  • Sumber daya yang dihapus atau dimodifikasi setelah pengiriman pekerjaan dilewati daripada ditambal, untuk menghindari penulisan perubahan bersamaan.

Penggunaan

$bulk-patchOperasi ini asinkron. Untuk memulai pekerjaan, kirimkan permintaan POST:

POST [base]/$bulk-patch

Untuk melakukan polling status pekerjaan, gunakan titik akhir deskripsi:

GET [base]/$bulk-patch/{jobId}

Untuk memulai $bulk-patch operasi, lakukan hal berikut:

  1. Kirim permintaan patch massal yang menentukan sumber daya target dan operasi patch. Tanggapan termasuk ID pekerjaan.

  2. Jajak pendapat status pekerjaan menggunakan titik akhir deskripsi sampai statusnya COMPLETED atauCOMPLETED_WITH_ERRORS.

  3. Tinjau ringkasan pekerjaan untuk melihat berapa banyak sumber daya yang berhasil, gagal, atau dilewati.

Parameter

$bulk-patchOperasi mendukung parameter berikut.

Parameter Tipe Diperlukan Deskripsi
resourceType string Ya Jenis sumber daya FHIR untuk ditambal, misalnya Patient atauObservation.
resourceIds string [] Tidak Daftar ID sumber daya untuk ditambal. Ketika Anda menghilangkan parameter ini, operasi menambal semua sumber daya dari jenis yang ditentukan.
operations object Ya Operasi patch untuk diterapkan. Menerima array Patch JSON atau sumber Parameters daya Patch FHIR.
clientToken string Tidak User-provided token digunakan untuk memastikan idempotensi. Mengirimkan ulang pekerjaan dengan token klien yang sama mengembalikan pekerjaan yang ada alih-alih membuat yang baru.
validationLevel string Tidak Tingkat validasi FHIR diterapkan saat memperbarui setiap sumber daya. Nilai yang diterima adalah strict (default),structure-only, danminimal.

Menargetkan sumber daya

Anda dapat menargetkan sumber daya dalam dua mode.

Mode jenis sumber daya

Dalam mode tipe sumber daya, operasi menambal semua sumber daya dari jenis tertentu di datastore.

{
    "resourceType": "Patient",
    "operations": { ... }
}
Mode ID sumber daya

Dalam mode ID sumber daya, operasi menambal daftar sumber daya tertentu berdasarkan ID. Semua ID sumber daya harus tipe yang sama dan cocok dengan resourceType parameter. Format dapat berupa referensi lengkap ([resourceType]/[id]) atau hanya ID ([id]). Daftar dapat berisi hingga 50.000 ID sumber daya.

{
    "resourceType": "Patient",
    "resourceIds": ["Patient/001", "Patient/002", "Patient/003"],
    "operations": { ... }
}

Format patch yang didukung

$bulk-patchOperasi ini mendukung sintaks Patch JSON (RFC 6902) dan FHIR Patch (FHIRPath-based). Ini menggunakan set operasi yang didukung yang sama dan sintaks yang sama dengan operasi PATCH sinkron. Untuk informasi selengkapnya, lihat Memodifikasi Sumber Daya dengan Operasi PATCH.

Mulai contoh pekerjaan patch massal

Contoh berikut mengirimkan pekerjaan patch massal yang menambahkan tag kepatuhan ke Patient sumber daya tertentu menggunakan Patch FHIR.

Contoh Permintaan

POST [base]/$bulk-patch
Content-Type: application/json

{
    "resourceType": "Patient",
    "resourceIds": ["patient-1", "patient-2", "patient-3"],
    "validationLevel": "strict",
    "clientToken": "unique-idempotency-token-123",
    "operations": {
        "resourceType": "Parameters",
        "parameter": [
            {
                "name": "operation",
                "part": [
                    {"name": "type", "valueCode": "add"},
                    {"name": "path", "valueString": "Patient.meta"},
                    {"name": "name", "valueString": "tag"},
                    {"name": "value", "valueCoding": {
                        "system": "http://example.org/compliance",
                        "code": "2026-audit-complete"
                    }}
                ]
            }
        ]
    }
}
Contoh Respons

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "jobStatus": "SUBMITTED"
}

Polling status pekerjaan patch massal

Setelah Anda mengirimkan pekerjaan, jajak pendapat status pekerjaan untuk melacak kemajuan dan mengambil hasil. Transisi pekerjaan melalui SUBMITTED danIN_PROGRESS, dan kemudian ke keadaan terminal COMPLETED atauCOMPLETED_WITH_ERRORS.

GET [base]/$bulk-patch/{jobId}

Contoh berikut menunjukkan respons untuk pekerjaan yang sedang berlangsung.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "IN_PROGRESS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "summary": {
        "estimatedResourceCount": 1000
    }
}
catatan

estimatedResourceCountIni tepat untuk mode ID sumber daya, dan sama dengan ukuran daftar yang dikirimkan. Untuk mode tipe sumber daya, jumlah aktual sumber daya yang diproses mungkin sedikit berbeda karena sumber daya dapat dibuat atau dihapus saat pekerjaan sedang berjalan.

Ketika pekerjaan mencapai status terminal, respons deskripsi mencakup ringkasan penghitungan sumber daya yang berhasil, gagal, dan dilewati. Jika ada sumber daya yang gagal atau dilewati, tanggapan mencantumkan alasan di failedResources danskippedResources. Status pekerjaan adalah COMPLETED_WITH_ERRORS ketika ada kegagalan, apakah kesalahan pelanggan atau kesalahan server. Ukuran respons membatasi skippedResources daftar failedResources dan, sehingga mungkin terpotong. Periksa failedResourcesTruncated dan skippedResourcesTruncated untuk menentukan apakah daftar lengkap disertakan.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "COMPLETED_WITH_ERRORS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "endTime": "2026-09-14T07:08:34.930Z",
    "summary": {
        "estimatedResourceCount": 1000,
        "totalResourcesProcessed": 1000,
        "succeeded": 985,
        "failedWithCustomerError": 5,
        "failedWithServerError": 0,
        "skipped": 10
    },
    "failedResources": [
        {
            "resourceId": "Patient/patient-101",
            "message": "FHIR resource in payload failed FHIR validation rules."
        }
    ],
    "skippedResources": [
        {
            "resourceId": "Patient/patient-201",
            "message": "Resource was modified after job submission"
        },
        {
            "resourceId": "Patient/patient-202",
            "message": "Resource was deleted."
        },
        {
            "resourceId": "Patient/patient-203",
            "message": "Resource not found."
        }
    ],
    "failedResourcesTruncated": false,
    "skippedResourcesTruncated": false
}

Alasan umum yang dilewati

Operasi melewatkan sumber daya saat berada dalam cakupan tetapi tidak dapat menambal sumber daya karena statusnya berubah antara pengiriman dan pemrosesan pekerjaan. Sumber daya yang dilewati tidak dianggap kesalahan. Berikut ini adalah alasan umum bahwa sumber daya dilewati.

  • Sumber daya dimodifikasi setelah pengiriman pekerjaan — Sumber daya diperbarui oleh operasi lain setelah pekerjaan patch massal menangkap versinya pada waktu pengiriman. Dalam kasus yang jarang terjadi, sumber daya yang berhasil ditambal mungkin dilaporkan dilewati dengan alasan dimodifikasi setelah pengiriman pekerjaan. Ini diharapkan dan mungkin terjadi pada tingkat yang sangat rendah (1 dari jutaan sumber daya).

  • Sumber daya dihapus setelah pengiriman pekerjaan — Sumber daya dihapus setelah pekerjaan dikirimkan (mode jenis sumber daya). Tidak semua sumber daya yang dihapus dijamin akan muncul dalam daftar yang dilewati. Jika sumber daya dihapus sebelum pekerjaan mulai diproses, sumber daya tersebut dikecualikan dari lingkup pekerjaan sepenuhnya dan tidak tercermin dalam hasil pekerjaan.

  • Sumber daya telah dihapus — ID sumber daya yang ditentukan dalam keadaan dihapus (mode ID sumber daya).

  • Sumber daya tidak ditemukan — ID sumber daya yang ditentukan tidak ada (hanya mode ID sumber daya).

Kegagalan pelanggan umum

Sumber daya gagal ketika operasi tidak dapat menerapkan patch karena masalah dengan sumber daya atau operasi patch. Sumber daya yang gagal menyertakan pesan kesalahan dengan detail diagnostik. Berikut ini adalah kegagalan pelanggan yang umum.

  • Kegagalan validasi FHIR — Sumber daya yang ditambal gagal validasi FHIR. Patch massal menerapkan validasi FHIR pada seluruh sumber daya yang ditambal, bukan hanya bidang yang dimodifikasi. Kegagalan ini dapat terjadi ketika patch menghasilkan nilai bidang yang tidak valid, atau ketika sumber daya sudah berisi bidang yang tidak sesuai dengan FHIR. Gunakan validationLevel parameter untuk mengontrol ketegasan validasi.

  • Kegagalan aplikasi patch — Operasi patch tidak kompatibel dengan struktur sumber daya, misalnya, mengganti bidang yang tidak ada, atau menambahkan ke jalur non-array.

Praktik terbaik

Kami merekomendasikan praktik terbaik berikut saat Anda menggunakan $bulk-patch operasi.

  • Uji dengan PATCH sinkron terlebih dahulu. AWS HealthLake memvalidasi sintaks operasi patch pada pengiriman pekerjaan dan menolak payload yang tidak valid secara serempak. Namun, operasi patch yang valid secara sintaksis masih dapat gagal pada waktu pemrosesan jika tidak cocok dengan struktur sumber daya tersimpan yang mendasarinya. Memahami karakteristik sumber daya target Anda dan uji operasi patch Anda dengan operasi PATCH sinkron sebelum menjalankan tugas patch massal. Ini membantu Anda menghindari kegagalan skala besar.

  • Gunakan kesalahan dan alasan yang dilewati untuk men-debug. Tinjau skippedResources daftar failedResources dan dalam respon deskripsi untuk memahami mengapa sumber daya tertentu tidak ditambal.

  • Verifikasi status sumber daya sebelum mencoba lagi. Operasi patch pada dasarnya tidak berdaya. Menerapkan patch yang sama dua kali dapat menghasilkan hasil yang berbeda, misalnya, menambahkan tag yang sudah ada membuat duplikat. Setelah Anda melihat sumber daya yang dilewati atau gagal, verifikasi status sumber daya saat ini sebelum Anda mengirimkan pekerjaan coba lagi.

Otorisasi

$bulk-patchOperasi mendukung metode otorisasi berikut:

  • AWS Identity and Access Management (IAM) Signature Version 4 (SIGv4) untuk akses terprogram.

  • SMART pada FHIR dengan cakupan yang diperlukan berikut:

    • Tingkat cakupan — Hanya cakupan tingkat sistem yang didukung. Operasi menolak cakupan tingkat pasien dan tingkat pengguna.

    • Jenis sumber daya — Cakupan harus sesuai dengan jenis sumber daya yang ditargetkan oleh pekerjaan.

    • Oper asi — Cakupan yang diperlukan tergantung pada mode pekerjaan dan versi SMART:

      • Mulai pekerjaan (mode tipe sumber daya) - SMART v1 membutuhkan read dan cak write upan. Penyimpanan data SMART v2 membutuhkan search dan update cakupan.

      • Mulai pekerjaan (mode ID sumber daya) - SMART v1 membutuhkan read dan cak write upan. Penyimpanan data SMART v2 membutuhkan read dan update cakupan.

      • Jelaskan pekerjaan — Membutuhkan ruang read lingkup.

Karakteristik kinerja

$bulk-patchOperasi ini dirancang untuk pemrosesan volume tinggi dan berjalan secara asinkron.

  • Konkurensi — Setiap datastore mendukung maksimal 1 pekerjaan patch massal bersamaan. Operasi mengantri pekerjaan tambahan dan memulainya secara otomatis ketika pekerjaan saat ini selesai.

  • Skalabilitas — Setiap pekerjaan mendukung hingga 2 miliar sumber daya. Operasi menolak pekerjaan yang melebihi batas ini. Batas ini mencegah waktu pemrosesan yang berkepanjangan, di mana banyak sumber daya dapat mengubah status, dan menghindari penahanan konkurensi pekerjaan datastore untuk jangka waktu yang lama. Gunakan mode ID sumber daya untuk mempartisi beban kerja. Sampel respons saat pekerjaan melebihi skala yang didukung:

    "status": "COMPLETED_WITH_ERRORS",
"message": "The requested bulk patch operation exceeds the supported scale."

  • Operasi paralel — Patch massal tidak kompatibel dengan operasi penghapusan, impor, atau ekspor massal bersamaan pada penyimpanan data yang sama.

  • Pembat alan — Pekerjaan patch massal tidak dapat dibatalkan setelah dikirimkan.