שימוש ב-IBM Cloud Resource Controller API לניהול instances

ניתן להשתמש ב-IBM Cloud® Resource Controller REST API כדי לקבל, ליצור ולעדכן instances באופן פרוגרמטי.

כל נקודות הקצה של Resource Controller דורשות אימות על ידי העברת header בשם Authorization עם ה-bearer token. יש לעיין ב-מדריך הגדרת REST API.

קבלת instance

יש להשתמש בנקודת הקצה GET /v2/resource_instances/{crn} כדי לקבל מידע על instance מסוים. יש לקודד ב-URL את ה-CRN בנתיב.

בנוסף לשדות הסטנדרטיים של Resource Controller, התגובה כוללת שדות ספציפיים לקוונטום הן ב-parameters והן ב-extensions. extensions שומר את המטא-נתונים המנורמלים של ה-instance, בעוד ש-parameters שומר רק את הבקשה האחרונה לשינוי ה-instance. לכן, כדאי לקרוא מ-extensions ולא מ-parameters.

האובייקט extensions כולל את השדות הבאים:

instance_limit_seconds — מספר שלם, או null. מגבלת זמן השימוש עבור ה-instance. ראו הגדרת מגבלות הקצאה ל-instance.
usage_allocation_seconds — מספר שלם, או null. הזמן המוקצה ל-instance זה, שבו משתמש ה-fair-share scheduler כדי לקבוע את עדיפות התור. ראו הגדרת מגבלות הקצאה ל-instance.
backends — מערך של strings. רשימת ההיתרים של שמות ה-backends הזמינים ל-instance זה. ["ANY"] פירושו שכל ה-backends בתוכנית זמינים (ברירת המחדל). [] פירושו שאין backends זמינים.

שדה ה-backends עשוי להיות מיושן

שדה backends באובייקט extensions עשוי להיות מיושן. הדבר יכול לקרות כאשר IBM Quantum Support משנה את החשבון שלך באופן שמשפיע על instances. לדוגמה, כאשר backend מוסר מחשבון, השדה backends של ה-instance יתעדכן, אך שינוי זה עדיין לא בא לידי ביטוי ב-Resource Controller API.

במקום זאת, הפתרון העוקף הנוכחי הוא להשתמש ב-IBM Quantum Compute Service REST API עם נקודת הקצה GET /v1/backends. (יש לוודא שמגדירים את ה-header Service-CRN ל-CRN של ה-instance שלך.)

cURL
Python

יש לקודד ב-URL את ה-CRN בנתיב. יש להחליף כל : ב-%3A וכל / ב-%2F. לדוגמה, crn:v1:bluemix:... הופך ל-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())

קבלת רשימה של כל ה-instances

יש להשתמש בנקודת הקצה GET /v2/resource_instances כדי לקבל רשימה של כל ה-instances שלך. יש להגדיר את פרמטר השאילתה resource_id לערך b6049020-80f4-11eb-a0f7-e35ec9b4054f כדי לסנן ל-instances של IBM Quantum®.

אם לחשבון שלך יש כמה תוכניות ואתה רוצה לסנן לפי תוכנית, יש להגדיר את פרמטר השאילתה resource_plan_id לאחד מהערכים הבאים:

תוכנית	`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`

כל תוצאה כוללת את אותו שדה extensions כפי שמתואר ב-קבלת 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())

עדכון instance

יש להשתמש בנקודת הקצה PATCH /v2/resource_instances/{crn} כדי לעדכן את המגבלה, ההקצאה וה-backends המותרים עבור instance. יש לקודד ב-URL את ה-CRN בנתיב.

יש להעביר אובייקט JSON בשם parameters בגוף הבקשה עם השדות שברצונך לשנות, יחד עם ה-header "Content-Type: application/json". שדות שהושמטו יישארו ללא שינוי.

instance_limit_seconds — מספר שלם, או null. מגבלת זמן השימוש עבור ה-instance. ראו הגדרת מגבלות הקצאה ל-instance.
usage_allocation_seconds — מספר שלם, או null. הזמן המוקצה ל-instance זה, שבו משתמש ה-fair-share scheduler כדי לקבוע את עדיפות התור. ראו הגדרת מגבלות הקצאה ל-instance. לא רלוונטי ל-instances מסוג Pay-As-You-Go.
backends — מערך של strings. רשימת ההיתרים של שמות ה-backends הזמינים ל-instance זה. ["ANY"] פירושו שכל ה-backends בתוכנית זמינים. [] פירושו שאין backends זמינים.

תמיד יש לכלול חותמת זמן ייחודית

ה-API מתעלם באופן שקט מהבקשה אם parameters זהה לבקשה הקודמת. באובייקט parameters, יש תמיד לכלול שדה timestamp המוגדר לזמן הנוכחי כדי שכל בקשה תיחשב ייחודית.

התגובה של נקודת הקצה דומה ל-קבלת instance, כולל האופן שבו היא מטפלת באובייקט extensions.

cURL
Python

יש לקודד ב-URL את ה-CRN בנתיב. יש להחליף כל : ב-%3A וכל / ב-%2F. לדוגמה, crn:v1:bluemix:... הופך ל-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())

יצירת instance חדש

יש להשתמש בנקודת הקצה POST /v2/resource_instances כדי ליצור (להקצות) instance חדש. יש להעביר גוף JSON עם ה-header "Content-Type: application/json".

שדות נדרשים:

name — שם קריא לבני אדם עבור ה-instance.
target — האזור, כגון us-east או eu-de.
resource_plan_id — התוכנית עבור instance זה. ראו טבלת מזהי התוכניות.
resource_group — קבוצת המשאבים לשימוש.

ניתן גם לכלול אובייקט parameters כדי להגדיר ערכים ספציפיים לקוונטום:

instance_limit_seconds — מספר שלם, או null. מגבלת זמן השימוש עבור ה-instance. ראו הגדרת מגבלות הקצאה ל-instance.
usage_allocation_seconds — מספר שלם, או null. הזמן המוקצה ל-instance זה, שבו משתמש ה-fair-share scheduler כדי לקבוע את עדיפות התור. ראו הגדרת מגבלות הקצאה ל-instance. לא רלוונטי ל-instances מסוג Pay-As-You-Go.
backends — מערך של strings. רשימת ההיתרים של שמות ה-backends הזמינים ל-instance זה. ["ANY"] פירושו שכל ה-backends בתוכנית זמינים. [] פירושו שאין backends זמינים.

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

הגדרת גישה ל-Qiskit Functions על instance

יש להשתמש בהוראות הבאות כדי להגדיר גישה ל-Qiskit Functions על instance קיים של IBM Quantum Compute Service באמצעות IBM Cloud Resource Controller API. יש לפעול לפי ההוראות לפי הסדר, מכיוון שהפקודות מתבססות זו על זו. לדוגמה, משתנים כמו ה-token וה-URL מוגדרים בשלב אחד ומשמשים שוב בשלבים מאוחרים יותר.

דרישות מוקדמות

מפתח API של IBM Cloud (הנקרא גם token). במידת הצורך, ניתן ליצור את מפתח ה-API שלך ב-לוח הבקרה.
ה-CRN של ה-instance שברצונך להגדיר. ה-CRN של ה-instance מופיע בדף Instances שלך.

שלב 1: קבלת bearer token

יש להחליף את מפתח ה-API שלך ב-bearer token. תעביר את ה-token הזה ב-header של authorization בכל בקשות ה-resource controller. יש להריץ את הקוד הבא כדי ליצור 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) 

התגובה כוללת שדה access_token, שהוא ה-bearer token שלך. יש להעתיק ערך זה.

שלב 2: אימות גישה

לפני ביצוע שינויים כלשהם, יש לוודא שה-token שלך עובד ולבדוק את תצורת ה-instance הנוכחית.

cURL
Python

חשוב

יש לקודד את ה-CRN ידנית ב-URL בנתיב. יש להחליף כל : ב-%3A וכל / ב-%2F. לדוגמה, crn:v1:bluemix:... הופך ל-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 יקודד ב-URL לתוך הנתיב.
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"])

תגובת 200 OK מאשרת שה-token שלך תקף. תצורת ה-instance הנוכחית נמצאת בשדה extensions של התגובה. יש להשתמש בזה במקום ב-parameters, שעשוי להיות לא עדכני.

שלב 3: בדיקת תצורת הפונקציות ברמת החשבון

ניתן להעניק ל-instance גישה רק למה שהחשבון זכאי לו. לפני הגדרת ה-instance, יש לבדוק את תצורת החשבון כדי לדעת אילו פונקציות, מודלים עסקיים והרשאות זמינים להענקה. זהו מקור האמת עבור הערכים שתשלח בשלב 4.

יש לקרוא ל-GET /accounts/{id} ב-Qiskit Runtime API עם מפתח ה-API שלך. ה-{id} הוא מזהה החשבון שלך ללא הקידומת a/. ניתן למצוא אותו מתוך ה-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"))

כל תוכנית בתגובה כוללת מערך functions וכן, אם מוגדר, אובייקט custom_functions. אלה מפרטים את השם המדויק, הספק, המודל העסקי וההרשאות שניתן להעניק ל-instance תחת אותה תוכנית.

הערה

GET /accounts/{id} מציג מה אפשר להעניק ברמת החשבון. GET /functions (ראו אימות התוצאה) מציג מה כבר הוענק ל-instance מסוים. יש להשתמש בנקודת הקצה account כדי לגלות ערכים חוקיים, ובנקודת הקצה functions כדי לאמת את התוצאה.

שלב 4: הגדרת גישה לפונקציות

יש לעדכן את ה-instance כדי להעניק גישה ל-Catalog Functions ול-Custom Functions.

הערות חשובות

הערכים name, provider ו-business_model בפונקציות חייבים להתאים בדיוק לרשומות המוגדרות ברמת החשבון (ראו השלב הקודם). ההרשאות חייבות להיות תת-קבוצה לא ריקה מהרשאות החשבון עבור אותה פונקציה. באופן דומה, custom_functions.permissions חייב להיות תת-קבוצה לא ריקה מהרשאות ה-custom_functions של החשבון.
יש לכלול חותמת זמן ב-parameters בכל PATCH. ה-Resource Controller מבצע דה-דופליקציה לבקשות PATCH על ידי השוואת ה-parameters הנכנסים לערך האחרון שנשמר. אם הם תואמים, הבקשה נזנחת בשקט עם 200 OK מבלי להגיע לשירות. יש לכלול ערך חותמת זמן משתנה כדי למנוע זאת.

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

# חותמת זמן משתנה מונעת מה-Resource Controller לבצע דה-דופליקציה לבקשה.
_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"])

תגובת 200 OK מציינת הצלחה. התצורה המעודכנת מופיעה בשדה extensions של התגובה.

הסרת גישה לפונקציות

Catalog Functions

כדי להסיר Catalog Functions מ-instance, יש לשלוח PATCH עם "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()

גם הגדרת "functions": [] (מערך ריק) מנקה את Catalog Functions באותו אופן. null היא הצורה הקנונית.

Custom Functions

כדי להסיר Custom Functions מ-instance, יש לשלוח PATCH עם "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()

הגדרת "custom_functions": {"permissions": []} מנקה באופן שווה-ערך custom functions. null היא הצורה הקנונית.

אימות התוצאה

כדי לוודא שה-instance כולל את תצורת ה-Qiskit Functions הנכונה, יש להשתמש ב-GET /functions מ-Qiskit Runtime API במקום מ-Resource Controller. המצב השמור ב-Resource Controller עשוי להיות לא עדכני אם שינויים ברמת החשבון עדכנו את ה-instance מחוץ ל-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 מקבל את ה-CRN הגולמי, לא את הצורה המקודדת ב-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())

התגובה מפרטת את הפונקציות שיש ל-instance גישה אליהן כרגע.

קבלת instance​

קבלת רשימה של כל ה-instances​

עדכון instance​

יצירת instance חדש​

הגדרת גישה ל-Qiskit Functions על instance​

דרישות מוקדמות​

שלב 1: קבלת bearer token​

שלב 2: אימות גישה​

שלב 3: בדיקת תצורת הפונקציות ברמת החשבון​

שלב 4: הגדרת גישה לפונקציות​

הסרת גישה לפונקציות​

Catalog Functions​

Custom Functions​

אימות התוצאה​