उपयोग के निर्देश

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

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

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

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

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

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

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

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

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

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

---

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

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

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

पुष्टि करना

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

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

  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". अहम जानकारी: यह टैग, इन्फ़्रास्ट्रक्चर के लिए अनुमति वाली इमेज मैप में तय किए गए टैग से मेल खाना चाहिए. जैसे, "latest", "stable". अगर Terraform में SHA256 मैप तय किया गया है, तो सिस्टम, अनजान टैग को अस्वीकार कर देता है.
  • file_path (स्ट्रिंग): GCS बकेट में, उस फ़ोल्डर का पाथ जिसमें metrics_config.zip और publisher_config.zip शामिल हैं.
  • instance_type (स्ट्रिंग): Compute Engine मशीन टाइप. इस टाइप में, नेस्टेड वर्चुअलाइज़ेशन की सुविधा होनी चाहिए. जैसे, n1, n2 या t2d सीरीज़. ज़्यादा जानकारी के लिए, नेस्टेड वर्चुअलाइज़ेशन की खास जानकारी देखें.
  • owner (स्ट्रिंग): सिम्युलेशन शुरू करने वाले उपयोगकर्ता का ईमेल.
  • 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 तरीके का इस्तेमाल करते हैं.

1. सिम्युलेशन की सूची देखना

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

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

• क्वेरी पैरामीटर (सभी ज़रूरी नहीं हैं):

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

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

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

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

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

• एंडपॉइंट:

  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
  }
  

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

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

• रनिंग काउंट पाना: इससे, चल रहे सिम्युलेशन की संख्या मिलती है.

  • एंडपॉइंट:

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

  • सफल रिस्पॉन्स (200 OK):

    {
      "count": 0
    }
    

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

  • एंडपॉइंट:

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

  • सफल रिस्पॉन्स (200 OK):

    {
      "max_running_vms": 5
    }