उपयोगकर्ता मार्गदर्शिका

वेब डेमो का इस्तेमाल करके या सीधे तौर पर REST API को कॉल करके, सिमुलेशन चलाए जा सकते हैं.

इनपुट और आउटपुट

इनपुट और आउटपुट फ़ाइलें, Terraform सेटअप से Cloud Storage बकेट का इस्तेमाल करती हैं.

इनपुट डायरेक्ट्री में metrics_config.zip और publisher_config.zip फ़ाइलें होनी चाहिए. ज़रूरत के मुताबिक, इसका पाथ तय किया जा सकता है.

आउटपुट के लिए बनाए गए बकेट में simulations डायरेक्ट्री होती है. इसमें हर सिम्युलेशन को उसके आईडी के हिसाब से सेव किया जाता है. हर सिम्युलेशन डायरेक्ट्री में एक इनपुट फ़ोल्डर होता है. इसमें कॉपी की गई इनपुट फ़ाइलें और एक आउटपुट फ़ोल्डर होता है. आउटपुट फ़ोल्डर में, bugreport, logcat फ़ाइल, और जनरेट की गई सिम्युलेटर फ़ाइलें होती हैं.

वेब डेमो का इस्तेमाल करना

इस प्लैटफ़ॉर्म में, डेमोंस्ट्रेशन के लिए Flutter पर आधारित एक वेब ऐप्लिकेशन शामिल है. इसकी मदद से, सिमुलेशन देखे, बनाए, और मैनेज किए जा सकते हैं. हमारा सुझाव है कि आप अपनी ज़रूरतों के हिसाब से यूज़र इंटरफ़ेस बनाएं.

डेमो ऐप्लिकेशन को App Engine पर डिप्लॉय किया जाता है. इसके लिए, आपको Google खाते से साइन इन करना होगा. इसे आपके Google Cloud प्रोजेक्ट में कॉन्फ़िगर किए गए OAuth 2.0 क्लाइंट आईडी का इस्तेमाल करके सुरक्षित किया जाता है. साइन इन किए गए खाते के पास, डिप्लॉय किए गए Cloud Functions को लागू करने के लिए आईएएम अनुमतियां होनी चाहिए. उपयोगकर्ता खातों को ज़रूरी अनुमतियां देने के निर्देशों के लिए, आईएएम की मदद से ऐक्सेस की अनुमति देना लेख पढ़ें. जैसे, Cloud Functions Invoker की भूमिका (roles/cloudfunctions.invoker).

उपयोगकर्ता वर्कफ़्लो

1. अपने Google खाते से साइन इन करें. इसकी पुष्टि OAuth 2.0 प्रोसेस का इस्तेमाल करके की गई हो.
2. मुख्य पेज पर सिम्युलेशन देखें. इस पेज पर, Firestore डेटाबेस से क्वेरी करके सभी सिम्युलेशन की सूची बनाई जाती है. इस डेटाबेस में, सभी सिम्युलेशन के बारे में जानकारी होती है.
3. सबसे नीचे दाएं कोने में मौजूद, + ऐक्शन बटन पर क्लिक करके, नया सिम्युलेशन शेड्यूल करने के लिए किसी फ़ॉर्म पर जाएं. आपको कई पैरामीटर देने होते हैं. जैसे, इनपुट पाथ, बिल्ड आईडी, और इंस्टेंस टाइप. ज़्यादा जानकारी के लिए, सिमुलेशन बनाना लेख पढ़ें.
4. सिम्युलेशन की सूची में अपडेट किए गए मॉनिटर की स्थिति देखें. इससे नए सिम्युलेशन की स्थिति के बारे में पता चलता है. उदाहरण के लिए, PENDING, RUNNING, COMPLETED.
5. सिम्युलेशन पूरा होने के बाद, जनरेट की गई रिपोर्ट और आर्टफ़ैक्ट देखें. इनपुट फ़ाइलें, आउटपुट रिपोर्ट, लॉग, Logcat, और गड़बड़ी की रिपोर्ट, Cloud Storage में सेव की जाती हैं.
6. ज़रूरी नहीं: शेड्यूल किए गए या चल रहे सिम्युलेशन को रद्द करें.

एपीआई का इस्तेमाल करना

ऑटोमेशन और अन्य सिस्टम के साथ इंटिग्रेशन के लिए, REST API का इस्तेमाल किया जा सकता है.

Authentication सेक्शन और एंडपॉइंट की परिभाषाओं में इस्तेमाल किया गया प्लेसहोल्डर CLOUD_FUNCTION_URL, कॉल किए जा रहे Cloud फ़ंक्शन के बेस यूआरएल को दिखाता है. आपको Google Cloud Console में, Cloud Functions पेज पर फ़ंक्शन के यूआरएल मिल सकते हैं. हर फ़ंक्शन का यूआरएल, उसके फ़ंक्शन की जानकारी पेज के ट्रिगर टैब पर दिखता है. इसके अलावा, ये यूआरएल Terraform आउटपुट में भी देखे जा सकते हैं. ये आउटपुट, apply कमांड चलाने के बाद प्रिंट होते हैं.

पुष्टि करना

एपीआई के सभी अनुरोधों की पुष्टि, पहचान वाले टोकन से की जानी चाहिए. इससे कॉल करने वाले की पहचान की पुष्टि होती है. उपयोगकर्ता या सेवा खाते के पास, टारगेट फ़ंक्शन के लिए Cloud Functions Invoker की अनुमतियां होनी चाहिए.

1. उपयोगकर्ता के अनुरोध पर (लोकल और सीएलआई): अगर आपको किसी लोकल मशीन या Google Cloud से बाहर के एनवायरमेंट से एपीआई को चालू करना है, तो आपको Google की ओर से जारी किए गए ऐसे आइडेंटिटी टोकन का इस्तेमाल करना होगा जो किसी उपयोगकर्ता खाते के लिए मिला हो.

   TOKEN=$(gcloud auth print-identity-token)
   

2. Google Cloud में सेवा खाते का इस्तेमाल करना: Google Cloud संसाधन (उदाहरण के लिए, Compute Engine VM, कोई अन्य Cloud Function या Kubernetes क्लस्टर) से एपीआई को शुरू करते समय, संसाधन से जुड़े सेवा खाते की पहचान का इस्तेमाल करें. टोकन को संसाधन के मेटाडेटा सर्वर से फ़ेच किया जाना चाहिए.

   TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
   

अपने अनुरोधों के Authorization हेडर में, वापस पाए गए टोकन को Bearer टोकन के तौर पर शामिल करें.

एंडपॉइंट

Cloud Telemetry Simulation स्टैक के उपयोगकर्ता के लिए उपलब्ध एंडपॉइंट की मदद से, सिमुलेशन बनाए और मिटाए जा सकते हैं. इसके अलावा, डेटाबेस से सिमुलेशन की जानकारी पढ़ी जा सकती है.

सिमुलेशन तैयार करना

यह एंडपॉइंट, नया सिम्युलेशन अनुरोध बनाता है और उसे लागू करने के लिए शेड्यूल करता है.

• एंडपॉइंट: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

• अनुरोध का मुख्य हिस्सा:

  {
    "build_id": "latest",
    "file_path": "inputs/my-test-case/",
    "instance_type": "n1-standard-8",
    "owner": "user@example.com",
    "max_simulation_time": 300,
    "max_report_count": 5
  }
  

  • build_id (स्ट्रिंग): इस्तेमाल किए जाने वाले एजेंट के Docker इमेज का टैग. उदाहरण के लिए,latest.

  • file_path (string): GCS बकेट में मौजूद उस फ़ोल्डर का पाथ जिसमें metrics_config.zip और publisher_config.zip मौजूद हैं.

  • instance_type (string): Compute Engine का मशीन टाइप. इस तरह के टाइप में नेस्टेड वर्चुअलाइज़ेशन की सुविधा होनी चाहिए. जैसे, n1, n2 या t2d सीरीज़. ज़्यादा जानकारी के लिए, नेस्टेड वर्चुअलाइज़ेशन की खास जानकारी देखें.

  • owner (string): सिम्युलेशन शुरू करने वाले उपयोगकर्ता का ईमेल.

  • max_simulation_time (पूर्णांक): यह सिमुलेशन के चलने का ज़्यादा से ज़्यादा समय है. यह समय सेकंड में होता है.

  • max_report_count (पूर्णांक): टेलीमेट्री रिपोर्ट की वह संख्या जिसके बाद सिम्युलेशन खत्म हो जाता है.

• सफल अनुरोध का जवाब (200 OK):

  { "id": "sim-a1b2c3d4e5f6" }
  

सिम्युलेशन मिटाना

यह एंडपॉइंट, सिम्युलेशन को रद्द करता है. साथ ही, इससे जुड़े संसाधनों को मिटाता है.

• एंडपॉइंट: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
• हेडर:
  • Content-Type: application/json

• अनुरोध का मुख्य हिस्सा:

  { "id": "sim-a1b2c3d4e5f6" }
  

• सफल अनुरोध का रिस्पॉन्स (200 OK): एक खाली JSON ऑब्जेक्ट {}.

सिमुलेशन का डेटा पढ़ने की अनुमति दें

सिमुलेशन का डेटा पढ़ने के लिए, simulation-reader फ़ंक्शन का इस्तेमाल किया जा सकता है. ये एंडपॉइंट, इतिहास, स्टेटस, और सिस्टम कॉन्फ़िगरेशन को वापस पाने के लिए GET तरीके का इस्तेमाल करते हैं.

सिमुलेशन की सूची

यह फ़िल्टर करने और क्रम से लगाने की सुविधा के साथ, पेज के हिसाब से सिम्युलेशन की सूची वापस लाता है.

• एंडपॉइंट: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

• क्वेरी पैरामीटर (सभी वैकल्पिक हैं):

  • status (string): सिम्युलेशन की स्थिति (running, Simulation request received, cancelled या completed) के हिसाब से फ़िल्टर करें.
  • owner (string): मालिक के ईमेल के हिसाब से फ़िल्टर करें.
  • sort_by (string): इस फ़ील्ड के हिसाब से क्रम से लगाएं (received_at, status_updated_at, started_at). डिफ़ॉल्ट रूप से received_at पर सेट होता है.
  • sort_order (string): क्रम से लगाने की दिशा, asc या desc. डिफ़ॉल्ट रूप से, यह desc पर सेट होता है.
  • page_size (पूर्णांक): हर पेज पर नतीजों की संख्या. डिफ़ॉल्ट वैल्यू 20 होती है.
  • page_token (string): नतीजों का अगला पेज फ़ेच करने के लिए टोकन.

• अनुरोध का उदाहरण:

  curl -H "Authorization: Bearer $TOKEN"
  "https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"
  

• सफल अनुरोध का जवाब (200 OK):

  • सिमुलेशन की जानकारी देने वाला JSON ऑब्जेक्ट दिखाता है. इसमें सिमुलेशन की एक ऐरे और एक वैकल्पिक next_page_token शामिल होता है.

  {
    "simulations": [
      {
        "id": "1234-abcd",
        "owner": "some@email.com",
        "status": "completed",
        "status_updated_at": "2025-12-05T14:50:00.952Z",
        "received_at": "2025-12-05T14:46:43.106Z",
        "started_at": "2025-12-05T14:47:05.848Z",
        "ended_at": "0001-01-01T00:00:00Z",
        "instance_id": "sim-1234-abcd",
        "ip": "10.156.15.230",
        "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
        "instance_type": "n1-standard-8",
        "file_path": "gs://your-project-simulation_files/path/",
        "max_simulation_time": 60,
        "max_report_count": 1
      },
      {
        "id": "5678-efgh",
        "owner": "some@email.com",
        "status": "completed",
        "status_updated_at": "2025-11-07T14:49:54.25Z",
        "received_at": "2025-11-07T14:46:54.959Z",
        "started_at": "2025-11-07T14:47:13.714Z",
        "ended_at": "0001-01-01T00:00:00Z",
        "instance_id": "sim-5678-efgh",
        "ip": "10.156.15.221",
        "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
        "instance_type": "n1-standard-8",
        "file_path": "gs://your-project-simulation_files/path/",
        "max_simulation_time": 60,
        "max_report_count": 1
      }
    ],
    "next_page_token": "M7bydGsAptLncj8SOCb1"
  }
  

कोई खास सिम्युलेशन पाना

इस फ़ंक्शन की मदद से, किसी सिमुलेशन की पूरी जानकारी को उसकी आईडी के हिसाब से वापस पाया जा सकता है.

• एंडपॉइंट:

  GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]
  

• सफल रिस्पॉन्स (200 OK): यह एक JSON ऑब्जेक्ट दिखाता है. इसमें अनुरोध की गई सिम्युलेशन की जानकारी होती है.

  {
    "id": "1234-abcd",
    "owner": "some@email.com",
    "status": "completed",
    "status_updated_at": "2025-12-05T14:50:00.952Z",
    "received_at": "2025-12-05T14:46:43.106Z",
    "started_at": "2025-12-05T14:47:05.848Z",
    "ended_at": "0001-01-01T00:00:00Z",
    "instance_id": "sim-1234-abcd",
    "ip": "10.156.15.230",
    "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
    "instance_type": "n1-standard-8",
    "file_path": "gs://your-project-simulation_files/path/",
    "max_simulation_time": 60,
    "max_report_count": 1
  }
  

सिस्टम मेट्रिक और कॉन्फ़िगरेशन पाना

इन एंडपॉइंट से, सिम्युलेशन इन्फ़्रास्ट्रक्चर के मौजूदा लोड और कॉन्फ़िगरेशन के बारे में अहम जानकारी मिलती है.

• डेटा पॉइंट की कुल संख्या पाएं: इससे, चालू सिम्युलेशन की संख्या मिलती है.

  • एंडपॉइंट:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
    

  • सफल अनुरोध का जवाब (200 OK):

    {
      "count": 0
    }
    

• एक साथ चल रही ज़्यादा से ज़्यादा वर्चुअल मशीन पाएं: इससे, कॉन्फ़िगर की गई एक साथ चल रही ज़्यादा से ज़्यादा वर्चुअल मशीन की संख्या मिलती है.

  • एंडपॉइंट:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms
    

  • सफल अनुरोध का जवाब (200 OK):

    {
      "max_running_vms": 5
    }