Mengelola operasi yang berjalan lama

Halaman ini menjelaskan cara mengelola siklus proses operasi jangka panjang (LRO) Cloud Healthcare API.

Jika metode API mungkin memerlukan waktu lama untuk diselesaikan, metode tersebut dapat menampilkan Operation ke klien. Klien dapat menggunakan antarmuka Operation untuk mengambil status metode API secara asinkron dengan melakukan polling operasi. LRO di Cloud Healthcare API mematuhi pola desain LRO Google Cloud.

Cloud Healthcare API membuat LRO untuk beberapa metode, seperti projects.locations.datasets.fhirStores.import. Saat projects.locations.datasets.fhirStores.import dipanggil, Cloud Healthcare API membuat LRO untuk melacak status impor. LRO memiliki ID unik yang dapat Anda gunakan untuk melihat status LRO.

LRO dikelola di level set data. Jika Anda memanggil metode yang menampilkan LRO, seperti projects.locations.datasets.fhirStores.import, Anda dapat melihat status LRO dengan mengirimkan permintaan yang berisi ID LRO ke set data induk penyimpanan FHIR tempat impor terjadi.

Selain REST API, sumber berikut menghasilkan operasi yang berjalan lama saat Anda memanggil metode yang tercantum di Metode yang menampilkan LRO:

Google Cloud CLI
Halaman Cloud Healthcare API di Konsol Google Cloud

Anda dapat mengelola LRO Cloud Healthcare API menggunakan Konsol Google Cloud, Google Cloud CLI, atau REST API.

Catatan LRO disimpan selama sekitar 30 hari setelah LRO selesai, yang berarti Anda tidak dapat melihat atau mencantumkan LRO setelah itu.

Metode yang menampilkan LRO

Metode berikut menampilkan LRO.

Metode pengelolaan izin:

projects.locations.datasets.consentStores.queryAccessibleData

Metode set data:

Metode DICOM:

Metode FHIR:

Metode HL7v2:

Mendapatkan detail tentang LRO

Contoh berikut menunjukkan cara mendapatkan detail tentang LRO.

Versi Cloud Healthcare API yang ditampilkan dalam respons saat mendapatkan detail tentang LRO sama dengan versi API dari metode yang memulai LRO.

Konsol

Setelah memanggil metode menggunakan gcloud CLI atau API yang menampilkan LRO, Anda dapat melihat detail LRO di Konsol Google Cloud.

Di konsol Google Cloud, buka halaman Datasets.

Buka Set Data
Klik nama {i>dataset<i} berisi LRO yang ingin Anda lihat.
Klik Operasi.
Untuk melihat log error pada operasi di Cloud Logging, klik Actions, lalu klik View details in Cloud Logging. Untuk mengetahui informasi selengkapnya, baca artikel Melihat log error di Cloud Logging.
Untuk melihat detail selengkapnya tentang operasi, klik ID operasi yang sedang berjalan. Halaman Detail Operasi yang Berjalan Lama akan ditampilkan. Halaman ini menampilkan informasi berikut:
- Progres LRO
- Detail LRO, seperti ID operasi dan metode yang memanggil LRO
- {i>Subset<i} entri log

gcloud

Misalkan Anda menerima respons berikut setelah memanggil gcloud healthcare dicom-stores deidentify:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...

Respons tersebut menunjukkan bahwa Cloud Healthcare API membuat LRO dengan ID operasi. Anda juga dapat mengambil ID operasi dengan mencantumkan operasi database yang berjalan lama. Perintah terus berjalan hingga selesai, setelah itu menghasilkan output berikut:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...done
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

Untuk mendapatkan detail tentang LRO, jalankan perintah gcloud healthcare operations describe.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

PROJECT_ID: ID project Google Cloud Anda
DATASET_ID: ID set data
LOCATION: lokasi set data
OPERATION_ID: ID yang ditampilkan dari operasi yang berjalan lama

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

Anda akan melihat respons seperti berikut:

Respons

done: true
// 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: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  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
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary'

REST

Misalkan Anda menerima respons berikut setelah memanggil projects.locations.datasets.dicomStores.deidentify:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

Nilai name dalam respons menunjukkan bahwa Cloud Healthcare API membuat LRO bernama projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Anda juga dapat mengambil nama LRO dengan mencantumkan LRO.

Untuk mendapatkan status LRO, gunakan metode projects.locations.datasets.operations.get. Untuk melakukan polling LRO, panggil metode projects.locations.datasets.operations.get berulang kali sampai operasi selesai. Gunakan backoff di antara setiap permintaan polling, seperti 10 detik.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: ID project Google Cloud Anda
DATASET_ID: ID set data
LOCATION: lokasi set data
OPERATION_ID: ID yang ditampilkan dari operasi yang berjalan lama

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

Outputnya adalah sebagai berikut. Jika respons berisi "done": true, berarti operasi yang berjalan lama telah selesai.

Respons

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
    "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": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
  },
  // 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: ...,
        ...
      }
    ]
  }
}

Mencantumkan LRO

Contoh berikut menunjukkan cara mencantumkan LRO dalam set data.

Konsol

Untuk melihat daftar semua LRO dalam set data di Konsol Google Cloud, selesaikan langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Datasets.

Buka Set Data
Klik nama {i>dataset<i} berisi LRO yang ingin Anda lihat.
Klik Operasi.

Daftar LRO dalam set data dan statusnya akan ditampilkan. Untuk melihat log error di Cloud Logging, klik ikon informasi selengkapnya di kolom terakhir, lalu klik View details in Cloud Logging. Untuk mengetahui informasi lebih lanjut, baca bagian Melihat log error di Cloud Logging.

gcloud

Untuk mencantumkan LRO dalam set data, jalankan perintah gcloud healthcare operations list.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

DATASET_ID: ID set data
LOCATION: lokasi set data

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Anda akan melihat respons seperti berikut:

Respons

ID             LOCATION     DONE
OPERATION_ID   LOCATION {TRUE|FALSE}
...

REST

Untuk mencantumkan LRO dalam set data, gunakan metode projects.locations.datasets.operations.get.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: ID project Google Cloud Anda
DATASET_ID: ID set data
LOCATION: lokasi set data

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations"

PowerShell

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations" | Select-Object -Expand Content

APIs Explorer

Anda akan melihat respons JSON seperti berikut:

Respons

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
        "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
        "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": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
      },
      // 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: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

Membatalkan LRO

Contoh berikut menunjukkan cara membatalkan LRO dalam set data.

Konsol

Untuk membatalkan LRO di konsol Google Cloud, selesaikan langkah-langkah berikut:

Di konsol Google Cloud, buka halaman Datasets.

Buka Set Data
Klik nama {i>dataset<i} berisi LRO yang ingin Anda lihat.
Klik Operasi.
Di baris yang sama dengan LRO yang ingin dibatalkan, buka daftar Actions dan klik Stop Operation.

REST

Untuk membatalkan LRO, gunakan metode projects.locations.datasets.operations.cancel.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: ID project Google Cloud Anda
DATASET_ID: ID set data
LOCATION: lokasi set data
OPERATION_ID: ID yang ditampilkan dari operasi yang berjalan lama

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Jalankan perintah berikut:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel"

PowerShell

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

APIs Explorer

Anda akan melihat respons JSON seperti berikut:

Respons

{}

Untuk melihat status permintaan pembatalan, gunakan metode projects.locations.datasets.operations.get.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: ID project Google Cloud Anda
DATASET_ID: ID set data
LOCATION: lokasi set data
OPERATION_ID: ID yang ditampilkan dari operasi yang berjalan lama

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

APIs Explorer

Anda akan melihat respons JSON seperti berikut:

Respons

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "cancelRequested": true,
    "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,
  "error": {
    "code": 1,
    "message": "Operation cancelled by user. Any progress already completed by the operation will not be reverted."
  }
}

Membatalkan beberapa LRO

Untuk membatalkan beberapa LRO, selesaikan langkah-langkah berikut:

Panggil metode operations.list untuk mendapatkan nama operasi dalam set data.
Panggil metode operations.cancel pada setiap operasi.

Google menyediakan skrip Python yang dapat Anda gunakan untuk membatalkan semua operasi untuk set data tertentu.

Memecahkan masalah LRO

Jika LRO gagal, responsnya akan menyertakan kode error Google Cloud kanonis. Tabel berikut memberikan penjelasan penyebab untuk setiap kode dan rekomendasi cara menangani kode tersebut. Untuk banyak error, tindakan yang direkomendasikan adalah mencoba lagi permintaan tersebut menggunakan backoff eksponensial. Untuk mengetahui informasi cara mengimplementasikan backoff eksponensial di Cloud Healthcare API, lihat Mencoba ulang permintaan yang gagal.

Code	Enum	Deskripsi	Tindakan yang disarankan
1	`CANCELLED`	Operasi dibatalkan, biasanya oleh pemanggil.	Jalankan kembali operasi jika diinginkan.
2	`UNKNOWN`	Error ini mungkin ditampilkan jika nilai `Status` yang diterima dari ruang alamat lain berada di ruang error yang tidak diketahui di ruang alamat ini. Jika error API tidak menampilkan informasi yang cukup, error tersebut mungkin dikonversi menjadi error ini.	Coba lagi dengan backoff eksponensial.
3	`INVALID_ARGUMENT`	Klien menetapkan argumen yang tidak valid. Error ini berbeda dengan `FAILED_PRECONDITION`. `INVALID_ARGUMENT` menunjukkan argumen yang bermasalah, apa pun status sistemnya, seperti format nama file yang salah.	Jangan mencoba lagi tanpa memperbaiki masalah.
4	`DEADLINE_EXCEEDED`	Batas waktu berakhir sebelum operasi selesai. Untuk operasi yang mengubah status sistem, error ini mungkin ditampilkan bahkan jika operasi telah berhasil diselesaikan. Sebagai contoh, respons berhasil dari suatu server dapat tertunda selama waktu yang cukup lama hingga tenggat waktu berakhir.	Coba lagi dengan backoff eksponensial.
5	`NOT_FOUND`	Beberapa entity yang diminta, seperti resource FHIR, tidak ditemukan.	Jangan mencoba lagi tanpa memperbaiki masalah.
6	`ALREADY_EXISTS`	Entity yang coba dibuat oleh klien, seperti instance DICOM, sudah ada.	Jangan mencoba lagi tanpa memperbaiki masalah.
7	`PERMISSION_DENIED`	Pemanggil tidak memiliki izin untuk menjalankan operasi yang ditentukan. Kode error ini tidak menyiratkan bahwa permintaan valid atau entitas yang diminta ada atau memenuhi prasyarat lainnya.	Jangan mencoba lagi tanpa memperbaiki masalah.
8	`RESOURCE_EXHAUSTED`	Beberapa resource telah habis, seperti kuota per project. Lihat Praktik terbaik pengelolaan kuota guna mengetahui tindakan yang disarankan.	Coba lagi dengan backoff eksponensial. Kuota mungkin tersedia seiring waktu.
9	`FAILED_PRECONDITION`	Operasi tersebut ditolak karena sistem tidak dalam keadaan dibutuhkan untuk menjalankan operasi. Misalnya, direktori yang akan dihapus tidak kosong, atau operasi `rmdir` diterapkan ke non-direktori.	Jangan mencoba lagi tanpa memperbaiki masalah.
10	`ABORTED`	Operasi dibatalkan, umumnya karena masalah konkurensi seperti kegagalan pemeriksaan pengurut atau pembatalan transaksi.	Coba lagi dengan backoff eksponensial.
11	`OUT_OF_RANGE`	Operasi diupayakan melewati rentang yang valid, seperti mencari atau membaca akhir file. Tidak seperti `INVALID_ARGUMENT`, error ini menunjukkan masalah yang dapat diperbaiki jika status sistem berubah.	Jangan mencoba lagi tanpa memperbaiki masalah.
12	`UNIMPLEMENTED`	Operasi tidak diterapkan atau tidak didukung/diaktifkan di Cloud Healthcare API.	Jangan coba lagi.
13	`INTERNAL`	Error internal. Hal ini menunjukkan bahwa terjadi error tidak terduga saat memproses pada sistem yang mendasarinya.	Coba lagi dengan backoff eksponensial.
14	`UNAVAILABLE`	Cloud Healthcare API saat ini tidak tersedia. Kemungkinan besar ini hanya kondisi sementara, yang dapat diperbaiki dengan mencoba kembali menggunakan backoff. Perlu diketahui bahwa mencoba kembali operasi non-idempoten tidak selalu aman.	Coba lagi dengan backoff eksponensial.
15	`DATA_LOSS`	Data hilang atau rusak yang tidak dapat dipulihkan.	Hubungi administrator sistem Anda. Administrator sistem dapat menghubungi perwakilan dukungan jika terjadi kehilangan atau kerusakan data.
16	`UNAUTHENTICATED`	Permintaan tidak memiliki kredensial autentikasi yang valid untuk operasi.	Jangan mencoba lagi tanpa memperbaiki masalah.