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. Lihat Menetapkan batas alokasi instance.
usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance.
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
Python

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>'

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
Python

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>'

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. Lihat Menetapkan batas alokasi instance.
usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance. Tidak berlaku untuk instance Pay-As-You-Go.
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.

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
Python

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
    }
}"

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. Lihat Menetapkan batas alokasi instance.
usage_allocation_seconds — Integer, atau null. Waktu yang dialokasikan untuk instance ini, digunakan oleh fair-share scheduler untuk menentukan prioritas antrean. Lihat Menetapkan batas alokasi instance. Tidak berlaku untuk instance Pay-As-You-Go.
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.

cURL
Python

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
      }
  }'

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
Python

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 .

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
Python

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>'

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 adalah sumber kebenaran 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
Python

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

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} shows what is available to grant at the account level. GET /functions (see Verify the result) shows what a specific instance has already been granted. Use the account endpoint to discover valid values, and the functions endpoint to confirm the result.

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). Permissions harus berupa subset yang tidak kosong dari izin akun untuk fungsi 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
Python

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"
    ]
  }
}
}'

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

Fungsi Katalog

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

cURL
Python

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

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.

Fungsi Kustom

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

cURL
Python

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

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 bahwa instance memiliki konfigurasi Qiskit Functions yang benar, gunakan GET /functions 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.

cURL
Python

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

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

Respons mencantumkan functions yang saat ini bisa diakses oleh instance tersebut.

Mendapatkan sebuah instance​

Mendapatkan daftar semua instance​

Memperbarui sebuah instance​

Membuat instance baru​

Mengonfigurasi akses Qiskit Functions pada sebuah instance​

Prasyarat​

Langkah 1: Dapatkan bearer token​

Langkah 2: Verifikasi akses​

Langkah 3: Cari konfigurasi functions tingkat akun​

Langkah 4: Konfigurasikan akses functions​

Menghapus akses functions​

Fungsi Katalog​

Fungsi Kustom​

Verifikasi hasilnya​