# Hizmet Metrikleri

https://dev.wisecp.com/tr/hizmet-metrikleri

Kullanıma göre faturalamayı yapılandıran, ölçümleri ve kesilen dönem kayıtlarını okuyan beş uç.

## Genel Bakış

Metrik faturalama, sabit ücret yerine **kullanıma göre** ücretlendirmedir: disk, trafik, çağrı sayısı. Bu beş uç neyin ölçüleceğini yapılandırır, ölçülen değerleri okur ve kesilmiş dönem kayıtlarını gösterir.

Neyin ölçülebileceğini **modül** belirler; ne kadarının ücretsiz olduğunu, fiyat kademelerini ve üst sınırı ise hizmet başına siz yazarsınız. Liste ucu ikisini birlikte döndürür, böylece bir hizmette hangi metriklerin açılabileceğini tek istekte görürsünüz.

## Referans

### Metrikleri Listeleme

get/api/v1/admin/services/{id}/metrics

`Services/GetServiceMetrics` admin birleşik liste

Modülün ölçebildiği metriklerle hizmette yapılandırılmış olanları tek listede döndürür.

Dönen alanlar data[] — 10

keystringMetriğin anahtarı.

labelstringGörünen etiketi.

unitstringÖlçü birimi.

supportedboolModül bu metriği ölçebiliyor mu.

configuredboolHizmette yapılandırılmış mı. Yanlış olan satırlar yalnız neyin mümkün olduğunu gösterir.

enabledboolKullanım faturalanıyor mu.

includedfloatFaturalanmadan önce ücretsiz sayılan miktar.

max_valueintPanelde uygulanacak üst sınır.

schemestringFiyatlama şeması: `per_unit` her birimi aynı fiyatlar, `volume` toplamı düştüğü kademenin fiyatıyla çarpar, `graduated` her kademeyi kendi fiyatıyla toplar.

pricingobjectKademeler. Yapılandırılmamış metrikte boş dizi döner.

Hatalar 2

not_found404Hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/services/529/metrics' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/services/529/metrics', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/metrics');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Liste 'yapilandirilabilir' olanlari da tasir; kurulu olanlari 'configured' ile ayirin.
$metrics = Api::Services()->GetServiceMetrics(['id' => 529])['data'];

$live = array_filter($metrics, fn (array $m): bool => $m['configured'] && $m['enabled']);
```

Yanıt 200

```json
{
  "data": [
    {
      "key": "disk_space",
      "label": "Disk Space",
      "unit": "GB",
      "supported": true,
      "configured": true,
      "enabled": true,
      "included": 10,
      "max_value": 100,
      "scheme": "per_unit",
      "pricing": {
        "1-100": {
          "from": 1,
          "to": 100,
          "USD": { "enable": 1, "price": 0.5 }
        }
      }
    },
    {
      "key": "bandwidth",
      "label": "Bandwidth",
      "unit": "GB",
      "supported": true,
      "configured": false,
      "enabled": false,
      "included": 0,
      "max_value": 0,
      "scheme": "per_unit",
      "pricing": []
    }
  ]
}
```

### Metriği Yapılandırma

put/api/v1/admin/services/{id}/metrics/{metric}

`Services/UpdateServiceMetric` admin modüle haber verir

Tek bir metriğin ücretsiz miktarını, üst sınırını ve fiyat kademelerini yazar.

Gövde 5

enabledboolKullanımın faturalanmasını açar ya da kapatır. Açmak, fiyatı olan en az bir aktif para birimi ister.

includedfloatFaturalanmadan önce ücretsiz sayılan miktar.

max_valueintPanelde uygulanacak üst sınır. Sıfır göndermek mevcut sınıra dokunmaz.

schemestringFiyatlama şeması: `per_unit` her birimi aynı fiyatlar, `volume` toplamı düştüğü kademenin fiyatıyla çarpar, `graduated` her kademeyi kendi fiyatıyla toplar. Varsayılan `per_unit`.

pricingobject[]Fiyat kademeleri. Her kademe bir alt sınır, bir üst sınır ve para birimi kodu başına `{enable, price}` taşır. Üst sınırı alt sınırdan küçük ya da sıfır olan kademeler yok sayılır.

Dönen alanlar data — 6

keystringMetriğin anahtarı.

enabledboolKullanım faturalanıyor mu.

includedfloatÜcretsiz sayılan miktar.

max_valueintUygulanan üst sınır.

schemestringFiyatlama şeması.

pricingobjectDüzenlenmiş kademeler. Dizi olarak gönderdikleriniz, sınırlarından türetilmiş anahtarlarla nesneye dönüşerek döner.

Hatalar 5

not_found404Hizmet bulunamadı.

metric_required422Metrik anahtarı boş.

invalid_metric422Modül bu metriği ölçemiyor. Yalnız ilk yapılandırmada denetlenir.

currency_required422Açmak için fiyatı olan aktif para birimi yok.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PUT 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"included":10,"max_value":100,"scheme":"per_unit","pricing":[{"from":1,"to":100,"USD":{"enable":1,"price":0.5}}]}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    included: 10,
    max_value: 100,
    scheme: 'per_unit',
    pricing: [{ from: 1, to: 100, USD: { enable: 1, price: 0.5 } }],
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'enabled'  => true,
        'included' => 10,
        'scheme'   => 'per_unit',
        'pricing'  => [
            ['from' => 1, 'to' => 100, 'USD' => ['enable' => 1, 'price' => 0.5]],
        ],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kademeler DIZI gonderilir, NESNE olarak geri doner: okudugunuzu oldugu gibi geri gondermeyin.
$current = Api::Services()->GetServiceMetrics(['id' => 529])['data'][0];
$tiers   = array_values($current['pricing']);

Api::Services()->UpdateServiceMetric([
    'id'      => 529,
    'metric'  => 'disk_space',
    'pricing' => $tiers,
]);
```

Yanıt 422

```json
{
  "error": {
    "code": "currency_required",
    "message": "Enabling a metric requires at least one currency with a price."
  }
}
```

### Metriği Kaldırma

delete/api/v1/admin/services/{id}/metrics/{metric}

`Services/DeleteServiceMetric` admin geçmiş korunur

Metriği hizmetin yapılandırmasından çıkarır. Kullanım ve faturalama kayıtları yerinde kalır.

Dönen alanlar data — 2

deletedboolKaldırma başarılı mı.

metricstringKaldırılan metriğin anahtarı.

Hatalar 2

not_found404Metrik bu hizmette yapılandırılmamış.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kaldirmak gecmisi SILMEZ: faturalama satirlari sorgulanmaya devam eder.
$response = Api::Services()->DeleteServiceMetric([
    'id'     => 529,
    'metric' => 'disk_space',
]);
```

### Kullanımı Okuma

get/api/v1/admin/services/{id}/metrics/{metric}/usage

`Services/GetServiceMetricUsage` admin en çok 370 gün

Verilen dönem için günlük kullanım noktalarını döndürür.

Sorgu parametreleri 2

period_startdatezorunluDönemin başlangıç günü.

period_enddatezorunluDönemin bitiş günü. Başlangıçtan önce olamaz ve aradaki fark 370 günü aşamaz.

Dönen alanlar data — 4

metricstringMetriğin anahtarı.

period_startdateDönemin başlangıcı.

period_enddateDönemin bitişi.

pointsobject[]Günlük noktalar; her biri bir tarih ve bir değer taşır. O gün ölçüm yoksa değer boş gelir — sıfır değil.

Hatalar 4

not_found404Hizmet bulunamadı.

invalid_period422Tarih çözümlenemedi ya da bitiş başlangıçtan önce.

period_too_long422Aralık 370 günü aşıyor.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -G 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/usage' \
  -H "Authorization: Bearer $API_KEY" \
  -d period_start=2026-06-01 \
  -d period_end=2026-06-30
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/usage');
url.searchParams.set('period_start', '2026-06-01');
url.searchParams.set('period_end', '2026-06-30');

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```

```php
$url = 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/usage?' . http_build_query([
    'period_start' => '2026-06-01',
    'period_end'   => '2026-06-30',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$usage = Api::Services()->GetServiceMetricUsage(
    ['id' => 529, 'metric' => 'disk_space'],
    ['period_start' => '2026-06-01', 'period_end' => '2026-06-30'],
);

// Bos deger 'o gun sifir kullanim' DEGIL 'o gun olcum yok' demektir.
$measured = array_filter($usage['data']['points'], fn (array $p): bool => $p['value'] !== null);
```

### Faturalama Geçmişini Okuma

get/api/v1/admin/services/{id}/metrics/{metric}/billing

`Services/GetServiceMetricBilling` admin

Metrik için kesilmiş dönem kayıtlarını döndürür.

Dönen alanlar data[] — 13

idintFaturalama satırının kimliği.

metricstringMetriğin anahtarı.

period_startdateDönemin başlangıcı.

period_enddateDönemin bitişi.

total_usagefloatDönemdeki toplam kullanım.

includedfloatÜcretsiz sayılan miktar.

overagefloatÜcretsiz miktarı aşan ve faturalanan kısım.

unit_pricefloatBirim fiyat.

amountfloatTutar.

currency_idintPara birimi kimliği.

invoice_idintBağlı faturanın kimliği. Henüz faturaya bağlanmadıysa sıfır.

statusstringSatırın durumu.

created_atstringSatırın oluşturulduğu zaman.

Hatalar 2

not_found404Hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/billing' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/billing', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/billing');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$rows = Api::Services()->GetServiceMetricBilling([
    'id'     => 529,
    'metric' => 'disk_space',
])['data'];

// Faturaya baglanmamis satirlar henuz tahsil edilmemistir.
$pending = array_filter($rows, fn (array $r): bool => $r['invoice_id'] === 0);
```

## Tuzaklar

> **Kademeler dizi gider, nesne döner**
> 
> Fiyat kademelerini **dizi** olarak gönderirsiniz ama yanıt bunları sınırlarından türetilmiş anahtarlarla **nesne** olarak döndürür. Okuduğunuzu olduğu gibi geri göndermek çalışmaz; önce değerleri düz diziye çevirmeniz gerekir.

> **Boş değer sıfır kullanım demek değildir**
> 
> Kullanım noktalarında bir günün değeri boş geliyorsa o gün **ölçüm alınmamıştır**; kullanımın sıfır olduğu anlamına gelmez. Boşları sıfır sayarak ortalama alan bir hesap, ölçümün durduğu günleri kullanımın düştüğü günler gibi gösterir.

> **Metriği kaldırmak geçmişi silmez**
> 
> Kaldırma ucu metriği yalnız yapılandırmadan çıkarır. Kullanım noktaları ve faturalama satırları yerinde kalır ve sorgulanmaya devam eder — kesilmiş bir tutar kaybolmaz. Metriği yeniden yapılandırdığınızda eski geçmiş yanında durur.

> **Açmak fiyatlı bir para birimi ister**
> 
> Bir metriği faturalamaya açmak, kademelerde fiyatı olan **en az bir aktif para birimi** ister; yoksa istek `currency_required` ile döner. Ücretsiz miktarı ayarlamak için açmanız gerekmez: kapalı bir metrikte de `included` yazabilirsiniz.

## İlgili Makaleler

- [Hizmet Uçları](https://dev.wisecp.com/tr/hizmet-uclari)
- [Hizmet Ayarları ve Sunucu](https://dev.wisecp.com/tr/hizmet-ayarlari-ve-sunucu)