ข้ามไปยังเนื้อหาหลัก

ใช้ IBM Cloud Resource Controller API เพื่อจัดการ instance

คุณสามารถใช้ IBM Cloud® Resource Controller REST API เพื่อ get, create และ update instances แบบ programmatic ได้

endpoint ทั้งหมดของ Resource Controller ต้องการให้คุณยืนยันตัวตนโดยส่ง header ที่ชื่อ Authorization พร้อม bearer token ดูที่ REST API setup guide

ดึงข้อมูล instance​

ใช้ endpoint GET /v2/resource_instances/{crn} เพื่อดึงข้อมูลเกี่ยวกับ instance บางตัว CRN ต้องเป็น URL-encoded ใน path

นอกเหนือจากฟิลด์มาตรฐานของ Resource Controller แล้ว การตอบกลับยังรวมฟิลด์เฉพาะของ quantum ทั้งใน parameters และ extensions extensions เก็บ metadata ที่ normalized ของ instance ในขณะที่ parameters เก็บเฉพาะคำขอล่าสุดที่ขอเปลี่ยนแปลง instance ดังนั้นคุณควรอ่านจาก extensions แทนที่จะเป็น parameters

object extensions มีฟิลด์เหล่านี้:

  • instance_limit_seconds — Integer หรือ null ขีดจำกัดเวลาการใช้งานของ instance ดูที่ Set instance allocation limits

  • usage_allocation_seconds — Integer หรือ null เวลาที่จัดสรรให้ instance นี้ ซึ่งใช้โดย fair-share scheduler เพื่อกำหนดลำดับความสำคัญในคิว ดูที่ Set instance allocation limits

  • backends — Array ของ strings รายการ allowlist ของชื่อ backend ที่ใช้ได้กับ instance นี้ ["ANY"] หมายถึง backends ทั้งหมดในแผนพร้อมใช้งาน (ค่าเริ่มต้น) [] หมายถึงไม่มี backends ที่ใช้งานได้

ฟิลด์ backends อาจล้าสมัย

ฟิลด์ backends ใน object extensions อาจล้าสมัยได้ สิ่งนี้เกิดขึ้นได้เมื่อ IBM Quantum Support เปลี่ยนแปลงบัญชีของคุณในลักษณะที่ส่งผลต่อ instance ตัวอย่างเช่น เมื่อมีการนำ backend ออกจากบัญชี ระบบจะอัปเดต backends ของ instance แต่การเปลี่ยนแปลงนั้นยังไม่สะท้อนใน Resource Controller API ในขณะนี้

แทนที่จะทำเช่นนั้น วิธีแก้ปัญหาปัจจุบันคือใช้ IBM Quantum Compute Service REST API กับ endpoint GET /v1/backends (ตรวจสอบให้แน่ใจว่าคุณตั้งค่า header Service-CRN เป็น CRN ของ instance คุณ)

CRN ต้องเป็น URL-encoded ใน path แทนที่ : แต่ละตัวด้วย %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>'

ดึงรายการ instance ทั้งหมด​

ใช้ endpoint GET /v2/resource_instances เพื่อดึงรายการ instance ทั้งหมดของคุณ ตั้งค่า query parameter resource_id เป็น b6049020-80f4-11eb-a0f7-e35ec9b4054f เพื่อกรองเฉพาะ instance ของ IBM Quantum®

หากบัญชีของคุณมีหลายแผนและคุณต้องการกรองตามแผน ให้ตั้งค่า query parameter resource_plan_id เป็นค่าใดค่าหนึ่งต่อไปนี้:

Planresource_plan_id
Premium7f666d17-7893-47d8-bf9d-2b2389fc4dfc
Flex53bde9d3-cdbb-46f5-a98f-60ebcadf7260
Pay-As-You-Go5304b575-3cff-4455-90dc-ae4367762093
Open850b21a7-71de-4e53-9441-1abdd202f35d

แต่ละผลลัพธ์มีฟิลด์ extensions เหมือนที่อธิบายไว้ใน Get an instance

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

อัปเดต instance​

ใช้ endpoint PATCH /v2/resource_instances/{crn} เพื่ออัปเดตขีดจำกัด การจัดสรร และ backends ที่อนุญาตสำหรับ instance CRN ต้องเป็น URL-encoded ใน path

ส่ง object JSON parameters ใน request body พร้อมฟิลด์ที่คุณต้องการเปลี่ยนแปลง พร้อมกับ header "Content-Type: application/json" ฟิลด์ที่ไม่ได้ระบุจะไม่มีการเปลี่ยนแปลง

  • instance_limit_seconds — Integer หรือ null ขีดจำกัดเวลาการใช้งานของ instance ดูที่ Set instance allocation limits

  • usage_allocation_seconds — Integer หรือ null เวลาที่จัดสรรให้ instance นี้ ซึ่งใช้โดย fair-share scheduler เพื่อกำหนดลำดับความสำคัญในคิว ดูที่ Set instance allocation limits ไม่สามารถใช้กับ instance แบบ Pay-As-You-Go

  • backends — Array ของ strings รายการ allowlist ของชื่อ backend ที่ใช้ได้กับ instance นี้ ["ANY"] หมายถึง backends ทั้งหมดในแผนพร้อมใช้งาน [] หมายถึงไม่มี backends ที่ใช้งานได้

ควรใส่ timestamp ที่ไม่ซ้ำกันเสมอ

API จะเพิกเฉยต่อคำขอโดยไม่แจ้งเตือนหาก parameters เหมือนกับคำขอก่อนหน้า ในออบเจ็กต์ parameters ให้ใส่ฟิลด์ timestamp ที่ตั้งเป็นเวลาปัจจุบันเสมอ เพื่อให้แต่ละคำขอถูกมองว่าไม่ซ้ำกัน

การตอบกลับของ endpoint นี้คล้ายกับ การดึงข้อมูล instance รวมถึงวิธีการจัดการ object extensions

CRN ต้องเป็น URL-encoded ใน path แทนที่ : แต่ละตัวด้วย %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
    }
}"

สร้าง instance ใหม่​

ใช้ endpoint POST /v2/resource_instances เพื่อสร้าง (provision) instance ใหม่ ส่ง JSON body พร้อม header "Content-Type: application/json"

ฟิลด์ที่จำเป็น:

  • name — ชื่อที่มนุษย์อ่านได้สำหรับ instance

  • target — ภูมิภาค เช่น us-east หรือ eu-de

  • resource_plan_id — แผนสำหรับ instance นี้ ดู ตาราง plan ID

  • resource_group — resource group ที่จะใช้

คุณสามารถรวม object parameters เพื่อตั้งค่าเฉพาะของ quantum ได้ด้วย:

  • instance_limit_seconds — Integer หรือ null ขีดจำกัดเวลาการใช้งานของ instance ดูที่ Set instance allocation limits

  • usage_allocation_seconds — Integer หรือ null เวลาที่จัดสรรให้ instance นี้ ซึ่งใช้โดย fair-share scheduler เพื่อกำหนดลำดับความสำคัญในคิว ดูที่ Set instance allocation limits ไม่สามารถใช้กับ instance แบบ Pay-As-You-Go

  • backends — Array ของ strings รายการ allowlist ของชื่อ backend ที่ใช้ได้กับ instance นี้ ["ANY"] หมายถึง backends ทั้งหมดในแผนพร้อมใช้งาน [] หมายถึงไม่มี backends ที่ใช้งานได้

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

ตั้งค่าการเข้าถึง Qiskit Functions บน instance​

ใช้คำแนะนำนี้เพื่อตั้งค่าการเข้าถึง Qiskit Functions บน instance ของ IBM Quantum Compute Service ที่มีอยู่แล้ว โดยใช้ IBM Cloud Resource Controller API ทำตามคำแนะนำตามลำดับ เนื่องจากคำสั่งต่าง ๆ ต่อยอดจากกันและกัน ตัวอย่างเช่น ตัวแปรอย่าง token และ URL ถูกตั้งค่าในขั้นตอนหนึ่งและนำมาใช้ซ้ำในขั้นตอนถัดไป

ข้อกำหนดเบื้องต้น​

  • IBM Cloud API key (เรียกอีกอย่างว่า token) หากจำเป็น ให้สร้าง API key ของคุณบน dashboard

  • CRN ของ instance ที่คุณต้องการตั้งค่า CRN ของ instance ปรากฏอยู่บนหน้า Instances ของคุณ

ขั้นตอนที่ 1: ขอรับ bearer token​

แลกเปลี่ยน API key ของคุณเป็น bearer token คุณจะส่ง token นี้ใน authorization header ของคำขอ resource controller ทั้งหมด รันโค้ดต่อไปนี้เพื่อสร้าง bearer token:

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 .

การตอบกลับมีฟิลด์ access_token ซึ่งเป็น bearer token ของคุณ คัดลอกค่านี้ไว้

ขั้นตอนที่ 2: ตรวจสอบการเข้าถึง​

ก่อนทำการเปลี่ยนแปลงใด ๆ ให้ยืนยันว่า token ของคุณใช้งานได้และตรวจสอบการตั้งค่า instance ปัจจุบัน

Important

CRN ต้องเป็น URL-encoded ด้วยตนเองใน path แทนที่ : แต่ละตัวด้วย %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>'

การตอบกลับ 200 OK ยืนยันว่า token ของคุณใช้งานได้ การตั้งค่า instance ปัจจุบันอยู่ในฟิลด์ extensions ของการตอบกลับ ใช้สิ่งนี้แทน parameters ซึ่งอาจล้าสมัย

ขั้นตอนที่ 3: ดูการตั้งค่า functions ระดับบัญชี​

instance สามารถได้รับสิทธิ์เข้าถึงเฉพาะสิ่งที่บัญชีมีสิทธิ์ใช้เท่านั้น ก่อนตั้งค่า instance ให้ดูการตั้งค่าของบัญชีเพื่อให้ทราบว่า functions, business models และ permissions ใดที่สามารถให้สิทธิ์ได้ นี่คือแหล่งข้อมูลจริงสำหรับค่าที่คุณจะส่งในขั้นตอนที่ 4

เรียก GET /accounts/{id} บน Qiskit Runtime API ด้วย API key ของคุณ {id} คือ ID บัญชีของคุณโดยไม่มี prefix a/ คุณสามารถหาได้จาก CRN ของ instance (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...)

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

แต่ละแผนในการตอบกลับมี array functions และหากมีการตั้งค่าไว้ object custom_functions สิ่งเหล่านี้แสดงชื่อ ผู้ให้บริการ business model และค่า permissions ที่แน่นอนซึ่งคุณสามารถให้สิทธิ์กับ instance ภายใต้แผนนั้นได้

หมายเหตุ

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.

ขั้นตอนที่ 4: ตั้งค่าการเข้าถึง functions​

อัปเดต instance เพื่อให้สิทธิ์เข้าถึง Catalog Functions และ Custom Functions

Important notes
  • ค่า name, provider และ business_model ใน functions ต้องตรงกับรายการที่ตั้งค่าไว้ในระดับบัญชีอย่างแน่นอน (ดูขั้นตอนก่อนหน้า) permissions ต้องเป็น subset ที่ไม่ว่างเปล่าของ permissions ของบัญชีสำหรับ function นั้น ในทำนองเดียวกัน custom_functions.permissions ต้องเป็น subset ที่ไม่ว่างเปล่าของ permissions custom_functions ของบัญชี
  • ใส่ timestamp ใน parameters ในทุก PATCH Resource Controller จะทำการ deduplicate คำขอ PATCH โดยเปรียบเทียบ parameters ที่เข้ามากับค่าล่าสุดที่จัดเก็บไว้ หากตรงกัน คำขอจะถูกทิ้งโดยไม่แจ้งเตือนด้วย 200 OK โดยไม่ไปถึง service ใส่ค่า timestamp ที่เปลี่ยนแปลงเพื่อป้องกันสิ่งนี้
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"
    ]
  }
}
}'

การตอบกลับ 200 OK บ่งชี้ว่าสำเร็จ การตั้งค่าที่อัปเดตแล้วปรากฏในฟิลด์ extensions ของการตอบกลับ

ยกเลิกการเข้าถึง functions​

ฟังก์ชันในแคตตาล็อก​

หากต้องการยกเลิก Catalog Functions ออกจาก instance ให้ส่ง PATCH พร้อม "functions": null:

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

การตั้งค่า "functions": [] (array ว่าง) มีผลเทียบเท่ากับการล้าง Catalog Functions null เป็นรูปแบบมาตรฐาน

ฟังก์ชันที่กำหนดเอง​

หากต้องการยกเลิก Custom Functions ออกจาก instance ให้ส่ง PATCH พร้อม "custom_functions": null:

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

การตั้งค่า "custom_functions": {"permissions": []} มีผลเทียบเท่ากับการล้าง custom functions null เป็นรูปแบบมาตรฐาน

ตรวจสอบผลลัพธ์​

หากต้องการยืนยันว่า instance มีการตั้งค่า Qiskit Functions ที่ถูกต้อง ให้ใช้ GET /functions จาก Qiskit Runtime API แทนที่ Resource Controller สถานะที่จัดเก็บของ Resource Controller อาจล้าสมัยได้หากการเปลี่ยนแปลงระดับบัญชีอัปเดต instance นอกเหนือจาก Resource Controller

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

การตอบกลับแสดงรายการ functions ที่ instance สามารถเข้าถึงได้ในปัจจุบัน

แหล่งที่มา: IBM Quantum docs — อัปเดตเมื่อ 12 ส.ค. 2569
เวอร์ชันภาษาอังกฤษ บน doQumentation — อัปเดตเมื่อ 12 ส.ค. 2569
ปัญหาเกี่ยวกับเว็บไซต์หรือการแปล?ปัญหาเกี่ยวกับเนื้อหา? แก้ไขที่ IBM Quantum docs