Menggunakan IBM Cloud Resource Controller API untuk manajemen instance

Kamu bisa menggunakan IBM Cloud® Resource Controller REST API untuk secara terprogram mendapatkan, membuat, dan memperbarui instance.

Semua endpoint Resource Controller mengharuskan kamu untuk melakukan autentikasi dengan meneruskan header bernama Authorization dengan bearer token. Lihat panduan setup REST API.

Mendapatkan sebuah instance

Gunakan endpoint GET /v2/resource_instances/{crn} untuk mendapatkan informasi tentang instance tertentu. CRN harus di-URL-encode dalam path.

Selain field standar Resource Controller, respons mencakup field khusus kuantum di parameters dan extensions. extensions menyimpan metadata instance yang sudah dinormalisasi, sedangkan parameters hanya menyimpan permintaan terbaru untuk mengubah instance. Oleh karena itu, kamu sebaiknya membaca dari extensions, bukan dari parameters.

Objek extensions mencakup field berikut:

• instance_limit_seconds — Integer, atau null. Batas waktu penggunaan untuk instance, dalam detik. Lihat Menetapkan batas alokasi instance.

• instance_limit_ru — Float, atau null. Batas penggunaan untuk instance, dalam resource unit (RU).

• usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, dalam detik, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance.

• usage_allocation_ru — Float, atau null. Alokasi untuk instance ini, dalam resource unit (RU).

• backends — Array berisi string. Daftar izin nama Backend yang tersedia untuk instance ini. ["ANY"] berarti semua Backend pada paket tersedia (default). [] berarti tidak ada Backend yang tersedia.

Field backends mungkin sudah usang

Field backends pada objek extensions mungkin sudah usang. Ini bisa terjadi ketika IBM Quantum Support mengubah akunmu dengan cara yang memengaruhi instance. Misalnya, ketika sebuah Backend dihapus dari akun, ini akan memperbarui backends untuk instance tersebut, tetapi perubahan itu saat ini belum tercermin di Resource Controller API.

Sebagai gantinya, solusi sementara saat ini adalah menggunakan IBM Quantum Compute Service REST API dengan endpoint GET /v1/backends. (Pastikan kamu menetapkan header Service-CRN ke CRN instance-mu.)

cURL

CRN harus di-URL-encode dalam path. Ganti setiap : dengan %3A dan setiap / dengan %2F. Misalnya, crn:v1:bluemix:... menjadi crn%3Av1%3Abluemix%3A....

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Python

import urllib.parse
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

resp = requests.get(
    url,
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Mendapatkan daftar semua instance

Gunakan endpoint GET /v2/resource_instances untuk mendapatkan daftar semua instance-mu. Tetapkan parameter kueri resource_id ke b6049020-80f4-11eb-a0f7-e35ec9b4054f untuk menyaring instance IBM Quantum®.

Jika akunmu memiliki beberapa paket dan kamu ingin menyaring berdasarkan paket, tetapkan parameter kueri resource_plan_id ke salah satu nilai berikut:

Paket	resource_plan_id
Premium	7f666d17-7893-47d8-bf9d-2b2389fc4dfc
Flex	53bde9d3-cdbb-46f5-a98f-60ebcadf7260
Pay-As-You-Go	5304b575-3cff-4455-90dc-ae4367762093
Open	850b21a7-71de-4e53-9441-1abdd202f35d

Setiap hasil mencakup field extensions yang sama seperti yang dijelaskan di Mendapatkan sebuah instance.

cURL

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Python

import requests

resp = requests.get(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f",
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Memperbarui sebuah instance

Gunakan endpoint PATCH /v2/resource_instances/{crn} untuk memperbarui batas, alokasi, dan Backend yang diizinkan untuk sebuah instance. CRN harus di-URL-encode dalam path.

Teruskan objek JSON parameters di body permintaan dengan field yang ingin kamu ubah, beserta header "Content-Type: application/json". Field yang dihilangkan tetap tidak berubah.

• instance_limit_seconds — Integer, atau null. Batas waktu penggunaan untuk instance, dalam detik. Lihat Menetapkan batas alokasi instance.

• instance_limit_ru — Float, atau null. Batas penggunaan untuk instance, dalam resource unit (RU).

• usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, dalam detik, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance. Tidak berlaku untuk instance Pay-As-You-Go.

• usage_allocation_ru — Float, atau null. Alokasi untuk instance ini, dalam resource unit (RU).

• backends — Array berisi string. Daftar izin nama Backend yang tersedia untuk instance ini. ["ANY"] berarti semua Backend pada paket tersedia. [] berarti tidak ada Backend yang tersedia.

Resource unit dan detik

Kamu tidak bisa menentukan parameter yang menggunakan detik dan RU sekaligus dalam satu permintaan; menentukan keduanya akan menghasilkan error. Jika kamu menentukan detik, nilai RU yang sesuai akan dihitung secara otomatis, begitu juga sebaliknya.

Selalu sertakan timestamp unik

API akan diam-diam mengabaikan permintaan jika parameters identik dengan permintaan sebelumnya. Dalam objek parameters, selalu sertakan field timestamp yang ditetapkan ke waktu saat ini agar setiap permintaan diperlakukan sebagai unik.

Respons endpoint ini mirip dengan mendapatkan sebuah instance, termasuk bagaimana ia menangani objek extensions.

cURL

CRN harus di-URL-encode dalam path. Ganti setiap : dengan %3A dan setiap / dengan %2F. Misalnya, crn:v1:bluemix:... menjadi crn%3Av1%3Abluemix%3A....

curl \
--request PATCH \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data "{
    \"parameters\": {
        \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",
        \"usage_allocation_seconds\": 220
    }
}"

Python

import urllib.parse
import datetime
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
body = {
    "parameters": {
        "timestamp": timestamp,
        "usage_allocation_seconds": 220,
    }
}

resp = requests.patch(
    url,
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Membuat instance baru

Gunakan endpoint POST /v2/resource_instances untuk membuat (menyediakan) instance baru. Teruskan body JSON dengan header "Content-Type: application/json".

Field yang wajib:

• name — Nama yang mudah dibaca manusia untuk instance tersebut.

• target — Region, seperti us-east atau eu-de.

• resource_plan_id — Paket untuk instance ini. Lihat tabel ID paket.

• resource_group — Resource group yang akan digunakan.

Kamu juga bisa menyertakan objek parameters untuk menetapkan nilai khusus kuantum:

• instance_limit_seconds — Integer, atau null. Batas waktu penggunaan untuk instance, dalam detik. Lihat Menetapkan batas alokasi instance.

• instance_limit_ru — Float, atau null. Batas penggunaan untuk instance, dalam resource unit (RU).

• usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, dalam detik, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance. Tidak berlaku untuk instance Pay-As-You-Go.

• usage_allocation_ru — Float, atau null. Alokasi untuk instance ini, dalam resource unit (RU).

• backends — Array berisi string. Daftar izin nama Backend yang tersedia untuk instance ini. ["ANY"] berarti semua Backend pada paket tersedia. [] berarti tidak ada Backend yang tersedia.

Resource unit dan detik

Kamu tidak bisa menentukan parameter yang menggunakan detik dan RU sekaligus dalam satu permintaan; menentukan keduanya akan menghasilkan error. Jika kamu menentukan detik, nilai RU yang sesuai akan dihitung secara otomatis, begitu juga sebaliknya.

cURL

curl \
  --request POST \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "name": "my-new-instance",
      "target": "us-east",
      "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
      "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
      "parameters": {
          "instance_limit_seconds": 300,
          "usage_allocation_seconds": 220
      }
  }'

Python

import requests

body = {
    "name": "my-new-instance",
    "target": "us-east",
    "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
    "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
    "parameters": {
        "instance_limit_seconds": 300,
        "usage_allocation_seconds": 220,
    },
}

resp = requests.post(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Mengonfigurasi akses Qiskit Functions pada sebuah instance

Gunakan instruksi berikut untuk mengonfigurasi akses Qiskit Functions pada instance IBM Quantum Compute Service yang sudah ada dengan menggunakan IBM Cloud Resource Controller API. Ikuti instruksi secara berurutan, karena setiap perintah dibangun berdasarkan perintah sebelumnya. Misalnya, variabel seperti token dan URL ditetapkan pada satu langkah dan digunakan kembali pada langkah-langkah berikutnya.

Prasyarat

• Sebuah IBM Cloud API key (juga disebut token). Jika perlu, buat API key-mu di dashboard.

• CRN dari instance yang ingin kamu konfigurasikan. CRN instance tercantum di halaman Instances milikmu.

Langkah 1: Dapatkan bearer token

Tukarkan API key-mu dengan bearer token. Kamu akan meneruskan token ini di header otorisasi dari semua permintaan resource controller. Jalankan kode berikut untuk menghasilkan bearer token:

cURL

curl --request POST \
--url 'https://iam.cloud.ibm.com/identity/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'apikey=<YOUR_API_KEY>&grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey'
--silent | jq .

Python

import requests

api_key = "<YOUR_API_KEY>"

resp = requests.post(
"https://iam.cloud.ibm.com/identity/token",
headers={"Content-Type": "application/x-www-form-urlencoded"},
params={
    "apikey": api_key,
    "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
},
timeout=30,
)
resp.raise_for_status()
token = resp.json()["access_token"]
print(token) 

Respons mencakup field access_token, yang merupakan bearer token-mu. Salin nilai ini.

Langkah 2: Verifikasi akses

Sebelum melakukan perubahan apa pun, pastikan token-mu berfungsi dan periksa konfigurasi instance saat ini.

cURL

Penting

CRN harus di-URL-encode secara manual dalam path. Ganti setiap : dengan %3A dan setiap / dengan %2F. Misalnya, crn:v1:bluemix:... menjadi crn%3Av1%3Abluemix%3A....

curl --request GET \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Python

import urllib.parse

crn = "<YOUR_INSTANCE_CRN>"
# CRN akan di-URL-encode ke dalam path.
instance_url = (
"https://resource-controller.cloud.ibm.com/v2/resource_instances/"
+ urllib.parse.quote(crn, safe="")
)
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

resp = requests.get(instance_url, headers=headers, timeout=30)
resp.raise_for_status()
print(resp.json()["extensions"])

Respons 200 OK memastikan bahwa token-mu valid. Konfigurasi instance saat ini ada di field extensions pada respons tersebut. Gunakan ini alih-alih parameters, yang mungkin sudah usang.

Langkah 3: Cari konfigurasi functions tingkat akun

Sebuah instance hanya bisa diberi akses ke apa yang berhak dimiliki akun tersebut. Sebelum mengonfigurasi instance, cari konfigurasi akun sehingga kamu tahu functions, model bisnis, dan izin mana yang tersedia untuk diberikan. Ini menjadi acuan utama untuk nilai yang akan kamu kirim pada Langkah 4.

Panggil GET /accounts/{id} pada Qiskit Runtime API dengan API key-mu. {id} adalah ID akunmu tanpa prefix a/. Kamu bisa menemukannya dari CRN instance (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...).

cURL

curl --request GET \
--url 'https://quantum.cloud.ibm.com/api/v1/accounts/<ACCOUNT_ID>' \
--header 'Authorization: apikey <YOUR_API_KEY>'

Python

account_id = "<ACCOUNT_ID>"  # from the CRN: crn:...:a/<ACCOUNT_ID>:...

resp = requests.get(
f"https://quantum.cloud.ibm.com/api/v1/accounts/{account_id}",
headers={"Authorization": f"apikey {api_key}"},
timeout=30,
)
resp.raise_for_status()
for plan in resp.json()["plans"]:
print(plan["plan_id"], plan.get("functions"), plan.get("custom_functions"))

Setiap paket dalam respons mencakup array functions dan, jika dikonfigurasi, sebuah objek custom_functions. Ini mencantumkan nama persis, provider, model bisnis, dan nilai izin yang bisa kamu berikan ke sebuah instance di bawah paket tersebut.

catatan

GET /accounts/{id} menunjukkan apa yang tersedia untuk diberikan di level akun. GET /entitlements (lihat Verifikasi hasil) menunjukkan apa yang sudah diberikan ke instance tertentu. Gunakan endpoint account untuk mencari nilai yang valid, dan endpoint entitlements untuk mengonfirmasi hasilnya.

Langkah 4: Konfigurasikan akses functions

Perbarui instance untuk memberikan akses ke Catalog Functions dan Custom Functions.

Catatan penting

• Nilai name, provider, dan business_model pada functions harus persis cocok dengan entri yang dikonfigurasi pada tingkat akun (lihat langkah sebelumnya). Izin (permissions) harus berupa subset yang tidak kosong dari izin akun untuk function tersebut. Demikian pula, custom_functions.permissions harus berupa subset yang tidak kosong dari izin custom_functions akun.
• Sertakan timestamp dalam parameters pada setiap PATCH. Resource Controller menghilangkan duplikasi permintaan PATCH dengan membandingkan parameters yang masuk dengan nilai terakhir yang tersimpan. Jika cocok, permintaan tersebut akan diam-diam dibatalkan dengan 200 OK tanpa mencapai layanan. Sertakan nilai timestamp yang berubah untuk mencegah hal ini.

cURL

curl --request PATCH \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parameters": {
  "timestamp": "2026-06-30T00:00:00Z",
  "functions": [
    {
      "name": "<FUNCTION_NAME>",
      "provider": "<PROVIDER>",
      "business_model": "<BUSINESS_MODEL>",
      "permissions": [
        "function.read",
        "function.run",
        "function-files.read",
        "function-files.write"
      ]
    }
  ],
  "custom_functions": {
    "permissions": [
      "function-custom.write",
      "function-custom.run"
    ]
  }
}
}'

Python

from datetime import datetime, timezone

# Timestamp yang berubah mencegah Resource Controller menghilangkan duplikasi permintaan.
_now = datetime.now(timezone.utc)
timestamp = _now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{_now.microsecond:06d}000Z"

body = {
"parameters": {
    "timestamp": timestamp,
    "functions": [
        {
            "name": "<FUNCTION_NAME>",
            "provider": "<PROVIDER>",
            "business_model": "<BUSINESS_MODEL>",
            "permissions": [
                "function.read",
                "function.run",
                "function-files.read",
                "function-files.write",
            ],
        }
    ],
    "custom_functions": {
        "permissions": ["function-custom.write", "function-custom.run"],
    },
}
}

resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()
print(resp.json()["extensions"])

Respons 200 OK menandakan keberhasilan. Konfigurasi yang diperbarui muncul di field extensions pada respons tersebut.

Menghapus akses functions

Catalog Functions

Untuk menghapus Catalog Functions dari sebuah instance, kirim PATCH dengan "functions": null:

cURL

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:01Z",
"functions": null
}
}'

Python

body = {"parameters": {"timestamp": timestamp, "functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

Menetapkan "functions": [] (array kosong) secara setara menghapus Catalog Functions. null adalah bentuk kanonik.

Custom Functions

Untuk menghapus Custom Functions dari sebuah instance, kirim PATCH dengan "custom_functions": null:

cURL

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:02Z",
"custom_functions": null
}
}'

Python

body = {"parameters": {"timestamp": timestamp, "custom_functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

Menetapkan "custom_functions": {"permissions": []} secara setara menghapus custom functions. null adalah bentuk kanonik.

Verifikasi hasilnya

Untuk memastikan instance memiliki konfigurasi Qiskit Functions yang benar, gunakan GET /entitlements dari Qiskit Runtime API alih-alih Resource Controller. Status tersimpan Resource Controller mungkin sudah usang jika perubahan tingkat akun memperbarui instance di luar Resource Controller.

Respons berisi array instance_entitlements dengan satu elemen untuk setiap instance yang diminta, yang menyertakan instance_crn. Periksa setiap elemen untuk melihat entitlement functions dan custom_functions-nya. Jika sebuah instance tidak bisa diperiksa, elemennya berisi error sebagai ganti entitlement. Jika field functions atau custom_functions tidak ada, berarti instance tersebut tidak diberi akses ke jenis itu.

Header Service-CRN menerima beberapa CRN instance yang dipisahkan koma, jadi kamu bisa memverifikasi beberapa instance sekaligus dalam satu permintaan.

cURL

curl --request GET \
--url 'https://quantum.cloud.ibm.com/api/v1/entitlements' \
--header 'Authorization: apikey <YOUR_API_KEY>' \
--header 'Service-CRN: <YOUR_INSTANCE_CRN>'

Python

# Header Service-CRN menggunakan CRN mentah, bukan bentuk yang di-URL-encode.
resp = requests.get(
"https://quantum.cloud.ibm.com/api/v1/entitlements",
headers={"Authorization": f"apikey {api_key}", "Service-CRN": crn},
timeout=30,
)
resp.raise_for_status()
print(resp.json())

Setiap elemen instance_entitlements menunjukkan apa saja yang saat ini bisa diakses oleh instance tersebut.