Gunakan IBM Cloud Resource Controller API untuk pengurusan instans

Anda boleh menggunakan IBM Cloud® Resource Controller REST API untuk mendapatkan, mencipta, dan mengemas kini instans secara programatik.

Semua titik akhir Resource Controller memerlukan anda mengesahkan diri dengan menghantar header bernama Authorization beserta token pembawa. Rujuk panduan persediaan REST API.

Dapatkan instans

Gunakan titik akhir GET /v2/resource_instances/{crn} untuk mendapatkan maklumat tentang instans tertentu. CRN mesti dikodkan URL dalam laluan tersebut.

Selain daripada medan Resource Controller standard, respons ini turut merangkumi medan khusus kuantum dalam kedua-dua parameters dan extensions. extensions menyimpan metadata ternormal bagi instans tersebut, manakala parameters hanya menyimpan permintaan terkini untuk mengubah suai instans tersebut. Oleh itu, anda seharusnya membaca daripada extensions dan bukan parameters.

Objek extensions merangkumi medan-medan berikut:

• instance_limit_seconds — Integer, atau null. Had masa penggunaan untuk instans tersebut, dalam saat. Lihat Tetapkan had peruntukan instans.

• instance_limit_ru — Float, atau null. Had penggunaan untuk instans tersebut, dalam unit sumber (RU).

• usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk instans ini, dalam saat, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan instans.

• usage_allocation_ru — Float, atau null. Peruntukan untuk instans ini, dalam unit sumber (RU).

• backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk instans ini. ["ANY"] bermakna semua Backend pada plan tersedia (lalai). [] bermakna tiada Backend yang tersedia.

Medan backends mungkin sudah lapuk

Medan backends dalam objek extensions mungkin sudah lapuk. Ini boleh berlaku apabila IBM Quantum Support mengubah akaun anda dengan cara yang memberi kesan kepada contoh. Sebagai contoh, apabila Backend dikeluarkan daripada akaun, ia akan mengemas kini backends untuk contoh tersebut, tetapi perubahan itu buat masa ini masih belum dicerminkan dalam Resource Controller API.

Sebaliknya, jalan penyelesaian semasa ialah menggunakan IBM Quantum Compute Service REST API bersama titik akhir GET /v1/backends. (Pastikan anda menetapkan header Service-CRN kepada CRN instans anda.)

cURL

CRN mesti dikodkan URL dalam laluan tersebut. Gantikan setiap : dengan %3A dan setiap / dengan %2F. Sebagai contoh, 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>"
# Kami menggunakan urllib.parse.quote untuk mengekod URL 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())

Dapatkan senarai semua instans

Gunakan titik akhir GET /v2/resource_instances untuk mendapatkan senarai semua instans anda. Tetapkan parameter pertanyaan resource_id kepada b6049020-80f4-11eb-a0f7-e35ec9b4054f untuk menapis kepada instans IBM Quantum®.

Jika akaun anda mempunyai pelbagai plan dan anda ingin menapis mengikut plan, tetapkan parameter pertanyaan resource_plan_id kepada salah satu nilai berikut:

Plan	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 merangkumi medan extensions yang sama seperti yang diterangkan dalam Dapatkan instans.

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())

Kemas kini instans

Gunakan titik akhir PATCH /v2/resource_instances/{crn} untuk mengemas kini had, peruntukan, dan Backend yang dibenarkan untuk sesuatu instans. CRN mesti dikodkan URL dalam laluan tersebut.

Hantar objek JSON parameters dalam badan permintaan berserta medan yang ingin anda ubah, bersama-sama header "Content-Type: application/json". Medan yang ditinggalkan akan kekal tidak berubah.

• instance_limit_seconds — Integer, atau null. Had masa penggunaan untuk instans tersebut, dalam saat. Lihat Tetapkan had peruntukan instans.

• instance_limit_ru — Float, atau null. Had penggunaan untuk instans tersebut, dalam unit sumber (RU).

• usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk instans ini, dalam saat, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan instans. Tidak terpakai untuk instans Pay-As-You-Go.

• usage_allocation_ru — Float, atau null. Peruntukan untuk instans ini, dalam unit sumber (RU).

• backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk instans ini. ["ANY"] bermakna semua Backend pada plan tersedia. [] bermakna tiada Backend yang tersedia.

Unit sumber dan saat

Anda tidak boleh menentukan parameter yang menggunakan saat dan RU sekali gus dalam permintaan yang sama; menentukan kedua-duanya akan mengembalikan ralat. Jika anda menentukan saat, nilai RU yang sepadan dikira secara automatik, dan sebaliknya.

Sentiasa sertakan cap masa yang unik

API akan mengabaikan permintaan secara senyap jika parameters sama dengan permintaan sebelumnya. Dalam objek parameters, sentiasa sertakan medan timestamp yang ditetapkan kepada masa semasa supaya setiap permintaan dianggap unik.

Respons titik akhir ini serupa dengan mendapatkan instans, termasuk cara ia mengendalikan objek extensions.

cURL

CRN mesti dikodkan URL dalam laluan tersebut. Gantikan setiap : dengan %3A dan setiap / dengan %2F. Sebagai contoh, 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>"
# Kami menggunakan urllib.parse.quote untuk mengekod URL 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())

Cipta instans baharu

Gunakan titik akhir POST /v2/resource_instances untuk mencipta (menyediakan) instans baharu. Hantar badan JSON berserta header "Content-Type: application/json".

Medan yang diperlukan:

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

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

• resource_plan_id — Plan untuk instans ini. Lihat jadual ID plan.

• resource_group — Kumpulan sumber yang hendak digunakan.

Anda juga boleh menyertakan objek parameters untuk menetapkan nilai khusus kuantum:

• instance_limit_seconds — Integer, atau null. Had masa penggunaan untuk instans tersebut, dalam saat. Lihat Tetapkan had peruntukan instans.

• instance_limit_ru — Float, atau null. Had penggunaan untuk instans tersebut, dalam unit sumber (RU).

• usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk instans ini, dalam saat, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan instans. Tidak terpakai untuk instans Pay-As-You-Go.

• usage_allocation_ru — Float, atau null. Peruntukan untuk instans ini, dalam unit sumber (RU).

• backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk instans ini. ["ANY"] bermakna semua Backend pada plan tersedia. [] bermakna tiada Backend yang tersedia.

Unit sumber dan saat

Anda tidak boleh menentukan parameter yang menggunakan saat dan RU sekali gus dalam permintaan yang sama; menentukan kedua-duanya akan mengembalikan ralat. Jika anda menentukan saat, nilai RU yang sepadan dikira secara automatik, dan 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())

Konfigurasikan akses Qiskit Functions pada instans

Gunakan arahan ini untuk mengkonfigurasikan akses Qiskit Functions pada contoh Perkhidmatan IBM Quantum Compute yang sedia ada dengan menggunakan IBM Cloud Resource Controller API. Ikut arahan mengikut urutan, kerana setiap arahan dibina berdasarkan arahan sebelumnya. Sebagai contoh, pemboleh ubah seperti token dan URL ditetapkan pada satu langkah dan digunakan semula pada langkah-langkah seterusnya.

Prasyarat

• Kunci API IBM Cloud (juga dipanggil token). Jika perlu, cipta kunci API anda pada papan pemuka.

• CRN bagi instans yang ingin anda konfigurasikan. CRN instans tersebut disenaraikan pada halaman Instans anda.

Langkah 1: Dapatkan token pembawa

Tukarkan kunci API anda untuk mendapatkan token pembawa. Anda akan menghantar token ini dalam header kebenaran bagi semua permintaan resource controller. Jalankan kod berikut untuk menjana token pembawa:

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 ini merangkumi medan access_token, iaitu token pembawa anda. Salin nilai ini.

Langkah 2: Sahkan akses

Sebelum membuat sebarang perubahan, sahkan bahawa token anda berfungsi dan periksa konfigurasi instans semasa.

cURL

Penting

CRN mesti dikodkan URL secara manual dalam laluan tersebut. Gantikan setiap : dengan %3A dan setiap / dengan %2F. Sebagai contoh, 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 dikodkan URL ke dalam laluan tersebut.
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 mengesahkan bahawa token anda sah. Konfigurasi instans semasa terdapat dalam medan extensions bagi respons tersebut. Gunakan ini dan bukannya parameters, yang mungkin sudah lapuk.

Langkah 3: Cari konfigurasi functions pada peringkat akaun

Sesuatu instans hanya boleh diberikan akses kepada apa yang layak diperoleh oleh akaun tersebut. Sebelum mengkonfigurasikan instans, cari konfigurasi akaun supaya anda tahu functions, model perniagaan, dan kebenaran mana yang tersedia untuk diberikan. Ini merupakan sumber kebenaran bagi nilai yang akan anda hantar dalam Langkah 4.

Panggil GET /accounts/{id} pada Qiskit Runtime API menggunakan kunci API anda. {id} ialah ID akaun anda tanpa awalan a/. Anda boleh menemuinya daripada CRN instans tersebut (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 plan dalam respons tersebut merangkumi tatasusunan functions dan, jika dikonfigurasikan, objek custom_functions. Ini menyenaraikan nama, penyedia, model perniagaan, dan nilai kebenaran yang tepat yang boleh anda berikan kepada sesuatu instans di bawah plan tersebut.

nota

GET /accounts/{id} menunjukkan apa yang boleh diberikan pada peringkat akaun. GET /entitlements (lihat Sahkan hasilnya) menunjukkan apa yang telah diberikan kepada instans tertentu. Gunakan titik akhir account untuk mengetahui nilai yang sah, dan titik akhir entitlements untuk mengesahkan hasilnya.

Langkah 4: Konfigurasikan akses functions

Kemas kini instans untuk memberikan akses kepada Catalog Functions dan Custom Functions.

Nota penting

• Nilai name, provider, dan business_model dalam functions mesti sepadan sepenuhnya dengan entri yang dikonfigurasikan pada peringkat akaun (lihat langkah sebelumnya). Permissions mesti merupakan subset tidak kosong daripada kebenaran akaun untuk function tersebut. Begitu juga, custom_functions.permissions mesti merupakan subset tidak kosong daripada kebenaran custom_functions akaun tersebut.
• Sertakan cap masa dalam parameters pada setiap PATCH. Resource Controller melakukan deduplikasi permintaan PATCH dengan membandingkan parameters yang masuk dengan nilai terakhir yang disimpannya. Jika sepadan, permintaan tersebut akan dibuang secara senyap dengan 200 OK tanpa sampai ke perkhidmatan. Sertakan nilai cap masa yang berubah untuk mengelakkan 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

# Cap masa yang berubah menghalang Resource Controller daripada melakukan deduplikasi permintaan tersebut.
_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 kejayaan. Konfigurasi yang dikemas kini muncul dalam medan extensions bagi respons tersebut.

Buang akses functions

Catalog Functions

Untuk membuang Catalog Functions daripada sesuatu instans, hantar 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": [] (tatasusunan kosong) turut mengosongkan Catalog Functions secara setara. null ialah bentuk kanonik.

Custom Functions

Untuk membuang Custom Functions daripada sesuatu instans, hantar 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": []} turut mengosongkan custom functions secara setara. null ialah bentuk kanonik.

Sahkan hasilnya

Untuk mengesahkan bahawa instans tersebut mempunyai konfigurasi Qiskit Functions yang betul, gunakan GET /entitlements daripada Qiskit Runtime API dan bukannya Resource Controller. Keadaan yang disimpan oleh Resource Controller mungkin sudah lapuk jika perubahan pada peringkat akaun mengemas kini instans tersebut di luar Resource Controller.

Respons mengandungi tatasusunan instance_entitlements dengan satu elemen bagi setiap instans yang diminta, yang merangkumi instance_crn. Periksa setiap elemen untuk melihat hak functions dan custom_functionsnya. Jika sesuatu instans tidak dapat disemak, elemennya mengandungi error dan bukannya hak akses. Medan functions atau custom_functions yang tiada bermaksud instans tersebut tidak diberikan jenis itu.

Pengepala Service-CRN menerima beberapa CRN instans yang dipisahkan dengan koma, supaya anda boleh mengesahkan beberapa instans 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 menerima CRN mentah, bukan bentuk yang dikodkan URL.
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 yang kini boleh diakses oleh instans tersebut.