Gamitin ang IBM Cloud Resource Controller API para sa pamamahala ng instance

Maaari mong gamitin ang IBM Cloud® Resource Controller REST API para programmatically na kumuha, lumikha, at mag-update ng mga instance.

Lahat ng endpoint ng Resource Controller ay nangangailangan na mag-authenticate ka sa pamamagitan ng pagpasa ng header na tinatawag na Authorization na may bearer token. Sumangguni sa REST API setup guide.

Kumuha ng instance

Gamitin ang GET /v2/resource_instances/{crn} endpoint para makakuha ng impormasyon tungkol sa isang partikular na instance. Ang CRN ay dapat na URL-encoded sa path.

Bukod sa mga standard na field ng Resource Controller, kasama sa response ang mga field na tukoy sa quantum sa parehong parameters at extensions. Iniimbak ng extensions ang normalized na metadata ng instance, samantalang ang parameters ay nag-iimbak lamang ng pinakahuling request na mag-modify sa instance. Kaya, dapat kang magbasa mula sa extensions sa halip na parameters.

Kasama sa object na extensions ang mga field na ito:

instance_limit_seconds — Integer, o null. Ang limitasyon ng oras ng paggamit para sa instance. Tingnan ang Set instance allocation limits.
usage_allocation_seconds — Integer, o null. Ang oras na inilaan para sa instance na ito, ginagamit ng fair-share scheduler para matukoy ang priyoridad sa pila. Tingnan ang Set instance allocation limits.
backends — Array ng mga string. Ang allowlist ng mga pangalan ng backend na available sa instance na ito. Ibig sabihin ng ["ANY"] na lahat ng backend sa plano ay available (ang default). Ibig sabihin ng [] na walang available na backend.

Maaaring luma na ang field na backends

Ang field na backends sa object na extensions ay maaaring luma na. Maaari itong mangyari kapag binago ng IBM Quantum Support ang iyong account sa paraang nakakaapekto sa mga instance. Halimbawa, kapag inalis ang isang backend mula sa isang account, iu-update nito ang backends para sa instance, ngunit ang pagbabagong iyon ay hindi pa naipapakita sa Resource Controller API sa kasalukuyan.

Sa halip, ang kasalukuyang workaround ay gamitin ang IBM Quantum Compute Service REST API kasama ang GET /v1/backends endpoint. (Siguraduhing itakda mo ang header na Service-CRN sa CRN ng iyong instance.)

cURL
Python

Ang CRN ay dapat na URL-encoded sa path. Palitan ang bawat : ng %3A at ang bawat / ng %2F. Halimbawa, ang crn:v1:bluemix:... ay nagiging 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())

Kumuha ng listahan ng lahat ng instance

Gamitin ang GET /v2/resource_instances endpoint para makakuha ng listahan ng lahat ng iyong instance. Itakda ang query parameter na resource_id sa b6049020-80f4-11eb-a0f7-e35ec9b4054f para mag-filter sa mga instance ng IBM Quantum®.

Kung ang iyong account ay may maraming plano at gusto mong mag-filter ayon sa plano, itakda ang query parameter na resource_plan_id sa isa sa mga sumusunod na halaga:

Plano	`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`

Kasama sa bawat resulta ang parehong field na extensions na inilarawan sa Get an 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())

I-update ang isang instance

Gamitin ang PATCH /v2/resource_instances/{crn} endpoint para i-update ang limit, allocation, at pinapayagang mga backend para sa isang instance. Ang CRN ay dapat na URL-encoded sa path.

Magpasa ng parameters JSON object sa request body kasama ang mga field na gusto mong baguhin, kasama ang header na "Content-Type: application/json". Ang mga field na hindi isinama ay mananatiling hindi nagbabago.

instance_limit_seconds — Integer, o null. Ang limitasyon ng oras ng paggamit para sa instance. Tingnan ang Set instance allocation limits.
usage_allocation_seconds — Integer, o null. Ang oras na inilaan para sa instance na ito, ginagamit ng fair-share scheduler para matukoy ang priyoridad sa pila. Tingnan ang Set instance allocation limits. Hindi applicable sa mga Pay-As-You-Go instance.
backends — Array ng mga string. Ang allowlist ng mga pangalan ng backend na available sa instance na ito. Ibig sabihin ng ["ANY"] na lahat ng backend sa plano ay available. Ibig sabihin ng [] na walang available na backend.

Palaging isama ang isang natatanging timestamp

Tahimik na binabalewala ng API ang request kung ang parameters ay kapareho ng nakaraang request. Sa object na parameters, palaging isama ang field na timestamp na itinakda sa kasalukuyang oras para ituring na natatangi ang bawat request.

Ang response ng endpoint ay katulad ng pagkuha ng isang instance, kasama ang paraan ng paghawak nito sa object na extensions.

cURL
Python

Ang CRN ay dapat na URL-encoded sa path. Palitan ang bawat : ng %3A at ang bawat / ng %2F. Halimbawa, ang crn:v1:bluemix:... ay nagiging 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())

Lumikha ng bagong instance

Gamitin ang POST /v2/resource_instances endpoint para lumikha (mag-provision) ng bagong instance. Magpasa ng JSON body kasama ang header na "Content-Type: application/json".

Mga kinakailangang field:

name — Isang pangalan para sa instance na madaling basahin ng tao.
target — Ang region, tulad ng us-east o eu-de.
resource_plan_id — Ang plano para sa instance na ito. Tingnan ang talahanayan ng plan ID.
resource_group — Ang resource group na gagamitin.

Maaari ka ring magsama ng parameters object para itakda ang mga halagang tukoy sa quantum:

instance_limit_seconds — Integer, o null. Ang limitasyon ng oras ng paggamit para sa instance. Tingnan ang Set instance allocation limits.
usage_allocation_seconds — Integer, o null. Ang oras na inilaan para sa instance na ito, ginagamit ng fair-share scheduler para matukoy ang priyoridad sa pila. Tingnan ang Set instance allocation limits. Hindi applicable sa mga Pay-As-You-Go instance.
backends — Array ng mga string. Ang allowlist ng mga pangalan ng backend na available sa instance na ito. Ibig sabihin ng ["ANY"] na lahat ng backend sa plano ay available. Ibig sabihin ng [] na walang available na backend.

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

I-configure ang access sa Qiskit Functions sa isang instance

Gamitin ang mga tagubiling ito para i-configure ang access sa Qiskit Functions sa isang umiiral nang instance ng IBM Quantum Compute Service sa pamamagitan ng paggamit ng IBM Cloud Resource Controller API. Sundin ang mga tagubilin ayon sa pagkakasunod-sunod, dahil ang mga command ay umaasa sa isa't isa. Halimbawa, ang mga variable tulad ng token at URL ay itinatakda sa isang hakbang at muling ginagamit sa mga susunod na hakbang.

Mga paunang kailangan

Isang IBM Cloud API key (tinatawag ding token). Kung kinakailangan, lumikha ng iyong API key sa dashboard.
Ang CRN ng instance na gusto mong i-configure. Ang CRN ng instance ay nakalista sa iyong pahina ng Instances.

Hakbang 1: Kumuha ng bearer token

Ipalit ang iyong API key sa isang bearer token. Ipapasa mo ang token na ito sa authorization header ng lahat ng resource controller request. Patakbuhin ang sumusunod na code para bumuo ng 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) 

Kasama sa response ang field na access_token, na siyang iyong bearer token. Kopyahin ang halagang ito.

Hakbang 2: I-verify ang access

Bago gumawa ng anumang pagbabago, kumpirmahin na gumagana ang iyong token at suriin ang kasalukuyang configuration ng instance.

cURL
Python

Mahalaga

Ang CRN ay dapat na manual na URL-encoded sa path. Palitan ang bawat : ng %3A at ang bawat / ng %2F. Halimbawa, ang crn:v1:bluemix:... ay nagiging 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>"
# Ise-URL-encode ang CRN at isasama sa 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"])

Kinukumpirma ng response na 200 OK na valid ang iyong token. Ang kasalukuyang configuration ng instance ay nasa field na extensions ng response. Gamitin ito sa halip na parameters, na maaaring luma na.

Hakbang 3: Alamin ang configuration ng functions sa antas ng account

Ang isang instance ay maaari lamang bigyan ng access sa kung ano lang ang pinahihintulutan sa account. Bago i-configure ang instance, alamin ang configuration ng account para malaman mo kung aling mga functions, business models, at permissions ang available na ibigay. Ito ang opisyal na batayan para sa mga halagang ipapadala mo sa Hakbang 4.

Tawagin ang GET /accounts/{id} sa Qiskit Runtime API gamit ang iyong API key. Ang {id} ay ang iyong account ID na walang prefix na a/. Makikita mo ito mula sa CRN ng 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"))

Kasama sa bawat plano sa response ang isang array na functions at, kung na-configure, isang object na custom_functions. Nakalista dito ang eksaktong pangalan, provider, business model, at mga halaga ng permissions na maaari mong ibigay sa isang instance sa ilalim ng planong iyon.

tala

Ipinapakita ng GET /accounts/{id} kung ano ang available na maibigay sa antas ng account. Ipinapakita naman ng GET /functions (tingnan ang I-verify ang resulta) kung ano na ang naibigay sa isang partikular na instance. Gamitin ang account endpoint para malaman ang mga valid na halaga, at ang functions endpoint para kumpirmahin ang resulta.

Hakbang 4: I-configure ang access sa functions

I-update ang instance para bigyan ito ng access sa Catalog Functions at Custom Functions.

Mahalagang tala

Ang mga halaga ng name, provider, at business_model sa functions ay dapat eksaktong tumugma sa mga entry na na-configure sa antas ng account (tingnan ang nakaraang hakbang). Ang permissions ay dapat na isang non-empty subset ng permissions ng account para sa function na iyon. Katulad nito, ang custom_functions.permissions ay dapat na isang non-empty subset ng mga permissions ng custom_functions ng account.
Magsama ng timestamp sa parameters sa bawat PATCH. Dine-deduplicate ng Resource Controller ang mga PATCH request sa pamamagitan ng paghahambing ng papasok na parameters sa huling halagang naimbak nito. Kung magkatugma ang mga ito, tahimik na binabalewala ang request (may 200 OK pa rin) nang hindi naaabot ang service. Magsama ng nagbabagong halaga ng timestamp para maiwasan ito.

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

# Ang isang nagbabagong timestamp ay pumipigil sa Resource Controller mula sa pag-de-duplicate ng request.
_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"])

Ang response na 200 OK ay nagpapahiwatig ng tagumpay. Ang na-update na configuration ay lilitaw sa field na extensions ng response.

Alisin ang access sa functions

Catalog Functions

Para alisin ang Catalog Functions mula sa isang instance, magpadala ng PATCH na may "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()

Ang pagtatakda ng "functions": [] (isang walang laman na array) ay katumbas na nag-a-clear ng Catalog Functions. Ang null ang canonical form.

Custom Functions

Para alisin ang Custom Functions mula sa isang instance, magpadala ng PATCH na may "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()

Ang pagtatakda ng "custom_functions": {"permissions": []} ay katumbas na nag-a-clear ng custom functions. Ang null ang canonical form.

I-verify ang resulta

Para kumpirmahin na ang instance ay may tamang configuration ng Qiskit Functions, gamitin ang GET /functions mula sa Qiskit Runtime API sa halip na ang Resource Controller. Ang naimbak na estado ng Resource Controller ay maaaring luma na kung ang mga pagbabago sa antas ng account ay nag-update sa instance sa labas ng 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>'

# Ang header na Service-CRN ay kumukuha ng raw na CRN, hindi ang URL-encoded na form.
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())

Ang response ay naglilista ng mga function na kasalukuyang may access ang instance.

Kumuha ng instance​

Kumuha ng listahan ng lahat ng instance​

I-update ang isang instance​

Lumikha ng bagong instance​

I-configure ang access sa Qiskit Functions sa isang instance​

Mga paunang kailangan​

Hakbang 1: Kumuha ng bearer token​

Hakbang 2: I-verify ang access​

Hakbang 3: Alamin ang configuration ng functions sa antas ng account​

Hakbang 4: I-configure ang access sa functions​

Alisin ang access sa functions​

Catalog Functions​

Custom Functions​

I-verify ang resulta​