Hizmet Metrikleri

1.7k görüntülenme Markdown

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 'https://panel.ornek.com/api/v1/admin/services/529/metrics' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/services/529/metrics', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 
{
  "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 -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}}]}'
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();
$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);
// 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 
{
  "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 -X DELETE 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space' \
  -H "Authorization: Bearer $API_KEY"
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();
$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);
// 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 -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
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();
$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);
$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 'https://panel.ornek.com/api/v1/admin/services/529/metrics/disk_space/billing' \
  -H "Authorization: Bearer $API_KEY"
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();
$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);
$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.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası