Kullanıcı kılavuzu

Sağlanan web demosunu kullanarak veya doğrudan REST API'yi çağırarak simülasyonlar çalıştırabilirsiniz.

Giriş ve çıkış

Giriş ve çıkış dosyaları, Terraform kurulumundaki Cloud Storage paketini kullanır.

Giriş dizini metrics_config.zip ve publisher_config.zip dosyalarını içermelidir. Gerekirse bu dosyanın yolunu tanımlayabilirsiniz.

Çıktıların bulunduğu pakette, her simülasyonu kimliğine göre depolayan bir simulations dizini bulunur. Her simülasyon dizini, kopyalanan giriş dosyalarını içeren bir giriş klasörü ve bir çıkış klasörü içerir. Çıkış klasöründe hata raporu, logcat dosyası ve oluşturulan simülatör dosyaları bulunur.

Web demosunu kullanma

Platformda, simülasyonları görüntülemenize, oluşturmanıza ve yönetmenize olanak tanıyan, gösterim amaçlı Flutter tabanlı bir web uygulaması bulunur. İhtiyaçlarınıza göre uyarlanmış kendi kullanıcı arayüzünüzü oluşturmanız önerilir.

Demo uygulaması App Engine'e dağıtılır ve Google Hesabı ile oturum açmanızı gerektirir. Bu, Google Cloud projenizde yapılandırılmış bir OAuth 2.0 istemci kimliği kullanılarak korunur. Oturum açılan hesabın, dağıtılan Cloud Functions işlevlerini çağırmak için IAM izinlerine sahip olması gerekir. Kullanıcı hesaplarına gerekli izinleri (ör. Cloud Functions Invoker rolü roles/cloudfunctions.invoker) verme talimatları için IAM ile erişimi yetkilendirme başlıklı makaleyi inceleyin.

Kullanıcı iş akışı

  1. OAuth 2.0 işlemi kullanılarak kimliği doğrulanmış Google Hesabınızla oturum açın.
  2. Tüm yürütme bilgilerini içeren Firestore veritabanına sorgu göndererek tüm simülasyonları listeleyen ana sayfada simülasyonları görüntüleyin.
  3. Sağ alt köşedeki + işlem düğmesini tıklayarak yeni bir simülasyon planlamak için bir forma gidin. Giriş yolu, derleme kimliği ve örnek türü gibi çeşitli parametreler sağlarsınız. Daha fazla bilgi için Simülasyon oluşturma başlıklı makaleyi inceleyin.
  4. Yeni simülasyonun durumunu gösteren simülasyon listesi güncellemelerindeki monitör durumunu kontrol edin (ör. PENDING, RUNNING, COMPLETED).
  5. Simülasyon tamamlandıktan sonra oluşturulan raporları ve yapıları görüntüleyin. Giriş dosyaları, çıkış raporları, günlükler, Logcat ve hata raporları Cloud Storage'da depolanır.
  6. İsteğe bağlı: Planlanmış veya devam eden bir simülasyonu iptal edin.

API kullanımı

Otomasyon ve diğer sistemlerle entegrasyon için REST API'yi kullanabilirsiniz.

Kimlik doğrulama bölümünde ve uç nokta tanımlarında kullanılan CLOUD_FUNCTION_URL yer tutucusu, çağrılan Cloud Function'ın temel URL'sini ifade eder. İşlev URL'lerini Google Cloud Console'daki Cloud Functions sayfasında bulabilirsiniz. Her işlevin URL'si, İşlev ayrıntıları sayfasının Tetikleyici sekmesinde gösterilir. Alternatif olarak, bu URL'leri bir apply komutu çalıştırdıktan sonra yazdırılan Terraform çıkışlarında bulabilirsiniz.

Kimlik doğrulama

Tüm API isteklerinin, arayanın kimliğini kanıtlayan bir kimlik jetonuyla kimliği doğrulanmış olması gerekir. Kimliğin (kullanıcı veya hizmet hesabı) hedef işlevde Cloud Functions Invoker izinlerine sahip olması gerekir.

  1. Kullanıcı çağırma (yerel ve KSA): API'yi yerel bir makineden veya Google Cloud dışı bir ortamdan çağırırken kullanıcı hesabı için alınmış, Google tarafından verilmiş bir kimlik jetonu kullanmanız gerekir.

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

  2. Hizmet hesabı çağırma (Google Cloud içinde): API'yi bir Google Cloud kaynağında (örneğin, Compute Engine sanal makinesi, başka bir Cloud Function veya Kubernetes kümesi) çağırırken kaynağın ekli hizmet hesabının kimliğini kullanın. Jeton, kaynağın meta veri sunucusundan alınmalıdır.

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

Alınan jetonu, isteklerinizin Authorization üstbilgisinde Bearer jetonu olarak ekleyin.

Uç noktalar

Cloud Telemetry Simulation yığınının kullanıcıya yönelik uç noktaları, simülasyon oluşturmanıza ve silmenize ya da veritabanından simülasyon bilgilerini okumanıza olanak tanır.

Simülasyon oluşturma

Bu uç nokta, yeni bir simülasyon isteği oluşturur ve yürütülmek üzere planlar.

  • Uç nokta: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • İstek metni:

    {
  "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 (dize): Kullanılacak aracı Docker görüntüsünün etiketi (ör. latest).

    • file_path (dize): metrics_config.zip ve publisher_config.zip öğelerini içeren klasörün GCS paketindeki yolu.

    • instance_type (dize): Compute Engine makine türü. Bu tür, n1, n2 veya t2d serisi gibi iç içe sanallaştırmayı desteklemelidir. Daha fazla bilgi için iç içe sanallaştırmaya genel bakış başlıklı makaleyi inceleyin.

    • owner (dize): Simülasyonu başlatan kullanıcının e-posta adresi.

    • max_simulation_time (tam sayı): Simülasyonun çalışacağı maksimum süre (saniye cinsinden).

    • max_report_count (tam sayı): Simülasyonun tamamlanacağı telemetri raporlarının sayısı.

  • Başarı yanıtı (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Simülasyon silme

Bu uç nokta, bekleyen veya çalışan bir simülasyonu iptal eder ve ilişkili kaynaklarını siler.

  • Uç nokta: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Başlıklar:
    • Content-Type: application/json

  • İstek metni:

    { "id": "sim-a1b2c3d4e5f6" }

  • Başarı yanıtı (200 OK): Boş bir JSON nesnesi {}.

Simülasyon verilerini okuma

Simülasyon verilerini okumak için simulation-reader işleviyle etkileşim kurabilirsiniz. Bu uç noktalar, geçmişi, durumu ve sistem yapılandırmasını almak için GET yöntemini kullanır.

Simülasyonları listeleme

Filtreleme ve sıralama desteğiyle birlikte, sayfalandırılmış bir simülasyon listesini alır.

  • Uç nokta: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Sorgu parametreleri (tümü isteğe bağlı):

    • status (dize): Simülasyon durumuna göre filtreleyin (running, Simulation request received, cancelled veya completed).
    • owner (dize): Sahibin e-postasına göre filtreleyin.
    • sort_by (dize): Sıralama yapılacak alan (received_at, status_updated_at, started_at). Varsayılan olarak received_at'dir.
    • sort_order (dize): Sıralama yönü, asc veya desc. Varsayılan olarak desc değerine ayarlanır.
    • page_size (tamsayı): Sayfa başına sonuç sayısı. Varsayılan değer 20'dir.
    • page_token (dize): Sonuçların sonraki sayfasını getirmek için kullanılan jeton.

  • Örnek istek:

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

  • Başarı yanıtı (200 OK):

    • Simülasyon dizisi ve isteğe bağlı bir next_page_token içeren bir JSON nesnesi döndürür.
    {
  "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"
}
Belirli bir simülasyonu alma

Belirli bir simülasyonun tüm ayrıntılarını kimliğine göre alır.

  • Uç nokta:

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

  • Başarı yanıtı (200 OK): İstenen simülasyonun ayrıntılarını içeren bir JSON nesnesi döndürür.

    {
  "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
}
Sistem metriklerini ve yapılandırmasını alma

Bu uç noktalar, simülasyon altyapısının mevcut yükü ve yapılandırması hakkında bilgi sağlar.

  • Çalışan simülasyonların sayısını alma: Çalışan simülasyonların sayısını döndürür.

    • Uç nokta:

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

    • Başarı yanıtı (200 OK):

      {
  "count": 0
}

  • Maksimum eşzamanlı sanal makine sayısını alma: Yapılandırılmış maksimum eşzamanlı çalışan sanal makine sayısını döndürür.

    • Uç nokta:

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

    • Başarı yanıtı (200 OK):

      {
  "max_running_vms": 5
}