Gunakan IBM Cloud Resource Controller API untuk pengurusan contoh

Anda boleh menggunakan IBM Cloud® Resource Controller REST API untuk mendapatkan, mencipta, dan mengemas kini contoh 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 contoh

Gunakan titik akhir GET /v2/resource_instances/{crn} untuk mendapatkan maklumat tentang contoh 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 contoh tersebut, manakala parameters hanya menyimpan permintaan terkini untuk mengubah suai contoh 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 contoh tersebut. Lihat Tetapkan had peruntukan contoh.
usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk contoh ini, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan contoh.
backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk contoh 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 contoh anda.)

cURL
Python

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

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 contoh

Gunakan titik akhir GET /v2/resource_instances untuk mendapatkan senarai semua contoh anda. Tetapkan parameter pertanyaan resource_id kepada b6049020-80f4-11eb-a0f7-e35ec9b4054f untuk menapis kepada contoh 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 contoh.

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

Kemas kini contoh

Gunakan titik akhir PATCH /v2/resource_instances/{crn} untuk mengemas kini had, peruntukan, dan Backend yang dibenarkan untuk sesuatu contoh. 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 contoh tersebut. Lihat Tetapkan had peruntukan contoh.
usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk contoh ini, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan contoh. Tidak terpakai untuk contoh Pay-As-You-Go.
backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk contoh ini. ["ANY"] bermakna semua Backend pada plan tersedia. [] bermakna tiada Backend yang tersedia.

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 contoh, termasuk cara ia mengendalikan objek extensions.

cURL
Python

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

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 contoh baharu

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

Medan yang diperlukan:

name — Nama yang mudah dibaca manusia untuk contoh tersebut.
target — Rantau, seperti us-east atau eu-de.
resource_plan_id — Plan untuk contoh 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 contoh tersebut. Lihat Tetapkan had peruntukan contoh.
usage_allocation_seconds — Integer, atau null. Masa yang diperuntukkan untuk contoh ini, digunakan oleh penjadual bahagian adil untuk menentukan keutamaan giliran. Lihat Tetapkan had peruntukan contoh. Tidak terpakai untuk contoh Pay-As-You-Go.
backends — Tatasusunan rentetan. Senarai putih nama Backend yang tersedia untuk contoh ini. ["ANY"] bermakna semua Backend pada plan tersedia. [] bermakna tiada 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())

Konfigurasikan akses Qiskit Functions pada contoh

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 contoh yang ingin anda konfigurasikan. CRN contoh tersebut disenaraikan pada halaman Instances 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
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 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 contoh semasa.

cURL
Python

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

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 contoh 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 contoh hanya boleh diberikan akses kepada apa yang layak diperoleh oleh akaun tersebut. Sebelum mengkonfigurasikan contoh, 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 contoh tersebut (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 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 contoh di bawah plan tersebut.

nota

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

Kemas kini contoh 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
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

# 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

Fungsi Katalog

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

Fungsi Tersuai

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

Sahkan hasilnya

Untuk mengesahkan bahawa contoh tersebut mempunyai konfigurasi Qiskit Functions yang betul, gunakan GET /functions daripada Qiskit Runtime API dan bukannya Resource Controller. Keadaan yang disimpan oleh Resource Controller mungkin sudah lapuk jika perubahan pada peringkat akaun mengemas kini contoh tersebut 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 menerima CRN mentah, bukan bentuk yang dikodkan URL.
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 ini menyenaraikan functions yang kini boleh diakses oleh contoh tersebut.

Dapatkan contoh​

Dapatkan senarai semua contoh​

Kemas kini contoh​

Cipta contoh baharu​

Konfigurasikan akses Qiskit Functions pada contoh​

Prasyarat​

Langkah 1: Dapatkan token pembawa​

Langkah 2: Sahkan akses​

Langkah 3: Cari konfigurasi functions pada peringkat akaun​

Langkah 4: Konfigurasikan akses functions​

Buang akses functions​

Fungsi Katalog​

Fungsi Tersuai​

Sahkan hasilnya​