İçeriğe geç
Sursa Developers

GET/v1/catalog/services

Katalogdaki hizmetleri listeleme

list_catalog_services

Harici hizmetlerin (SaaS ve tedarikçiler) ortak kataloğundaki kayıtları döndürür: ad, grup ya da web sitesi alan adında büyük/küçük harfe duyarsız alt dize araması, kategori filtresi ve sayfalama. Filtreye uyan toplam sayı X-Total-Count başlığındadır. Katalog tüm kuruluşlar tarafından paylaşılır ve oturum açmış her kullanıcıya açıktır. Verileri Sursa ile birlikte gelir ve her sürümde güncellenir (sürüm GET /v1/catalog/categories içinde ve her kaydın icon_url değerindeki version alanında bulunur).

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Sorgu parametreleri

  • qstring | null

    Adın, grubun ya da web sitesi alan adının alt dizesi (büyük/küçük harfe duyarsız).

    length ≤ 200

  • categorystring | null

    Kategorinin kısa adı (GET /v1/catalog/categories).

  • offsetinteger

    Varsayılan: 0≥ 0

  • limitinteger

    Varsayılan: 50≥ 1, ≤ 500

  • cursorstring

    Sonraki sayfanın imleci: aynı filtrelerle alınan önceki yanıtın X-Next-Cursor başlığından ya da next_cursor alanından alınır; sayfa boyutunu da taşır. offset ile birlikte: 422 validation.failed; başka bir listeye ya da başka filtrelere ait veya bozuk bir imleç: 400 api.cursor_invalid.

    length ≤ 512

Başlık parametreleri

  • X-View-Asstring

    Yalnızca admin rolündeki API anahtarları için. İsteği <profile>[:viewer|verifier|editor] veri profili adına yapar, örneğin employee:viewer. Kurulum anahtarı bu başlığı kullanamaz (403).

Çerez parametreleri

  • kb_view_asstring

    Bir oturum için “View as” modunun (başka bir kullanıcı gibi görüntüleme) çerezi. POST /auth/view-as bu çerezi ayarlar, DELETE /auth/view-as temizler.

Yanıtlar

200Başarılı yanıt

Yanıt başlıkları

  • Link

    Sonraki sayfanın adresi, <…>; rel="next". Başlık yoksa bu son sayfadır.

  • X-Next-Cursor

    cursor parametresi için sonraki sayfanın imleci. Başlık yoksa bu son sayfadır.

  • X-Total-Count

    limit ve offset değerlerinden bağımsız olarak filtreyle eşleşen toplam kayıt sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

array of CatalogService
  • categorystringzorunlu

    Kategorinin slug değeri (GET /v1/catalog/categories).

  • description_enstring | nullzorunlu

    İngilizce kısa açıklama. Açıklama yoksa null.

  • domainstring | nullzorunlu

    www. olmadan web sitesinin alan adı. Web sitesi yoksa null.

  • group_namestring | nullzorunlu

    Hizmet bir ürün ailesine aitse grup (tedarikçi), örneğin Atlassian; değilse null.

  • iconbooleanzorunlu

    Sursa ile birlikte bir simgenin gelip gelmediği.

  • icon_urlstring | nullzorunlu

    Simge URL’si (/v1/catalog/services/{service_id}/icon?v=… ya da kurulumun yapılandırdığı harici bir adres). Simge yoksa null.

  • idstring (uuid)zorunlu
  • namestringzorunlu
  • slugstringzorunlu
  • websitestring | nullzorunlu

    Web sitesinin URL’si (https://…) ya da null.

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

  • Retry-After

    İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← catalog · API başvurusu