Mine sisu juurde
Sursa Developers

GET/v1/catalog/services

Kataloogi teenuste loetlemine

list_catalog_services

Tagastab väliste teenuste (SaaS ja tarnijad) ülemaailmse kataloogi kirjed: tõstutundetu alamstringi otsing nimest, rühmast või veebisaidi domeenist, kategooriafilter ja lehitsemine. Filtrile vastavate kirjete koguarv on päises X-Total-Count. Kataloog on kõigi organisatsioonide ühine ja saadaval igale sisselogitud kasutajale. Selle andmed tulevad koos Sursaga ja uuenevad iga väljalaskega (versioon on päringu GET /v1/catalog/categories vastuses ja iga kirje aadressis icon_url parameetrina version).

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Päringuparameetrid

  • qstring | null

    Nime, rühma või veebisaidi domeeni alamstring (tõstutundetu).

    length ≤ 200

  • categorystring | null

    Kategooria lühinimi (GET /v1/catalog/categories).

  • offsetinteger

    Vaikimisi: 0≥ 0

  • limitinteger

    Vaikimisi: 50≥ 1, ≤ 500

  • cursorstring

    Järgmise lehe kursor päisest X-Next-Cursor või eelmise sama filtritega vastuse väljast next_cursor; see sisaldab lehe suurust. Koos parameetriga offset: 422 validation.failed; teise loendi kursor, teiste filtritega või vigane kursor: 400 api.cursor_invalid.

    length ≤ 512

Päiseparameetrid

  • X-View-Asstring

    Ainult rolliga admin API-võtmetele. Teeb päringu andmeprofiili <profile>[:viewer|verifier|editor] nimel, näiteks employee:viewer. Paigaldusvõti seda päist kasutada ei saa (403).

Küpsiseparameetrid

  • kb_view_asstring

    Seansi režiimi „View as“ küpsis. POST /auth/view-as määrab selle ja DELETE /auth/view-as kustutab selle.

Vastused

200Edukas vastus

Vastuse päised

  • Link

    Järgmise lehe aadress, <…>; rel="next". Päise puudumine tähendab, et see on viimane leht.

  • X-Next-Cursor

    Järgmise lehe kursor parameetri cursor jaoks. Päise puudumine tähendab, et see on viimane leht.

  • X-Total-Count

    Filtrile vastavate kirjete koguarv olenemata parameetritest limit ja offset.

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

array of CatalogService
  • categorystringkohustuslik

    Kategooria lühinimi (GET /v1/catalog/categories).

  • description_enstring | nullkohustuslik

    Lühikirjeldus inglise keeles. null, kui kirjeldust ei ole.

  • domainstring | nullkohustuslik

    Veebisaidi domeen ilma osata www.. null, kui veebisaiti ei ole.

  • group_namestring | nullkohustuslik

    Rühm (tarnija), kui teenus kuulub tooteperekonda, näiteks Atlassian; muul juhul null.

  • iconbooleankohustuslik

    Kas ikoon on Sursaga kaasas.

  • icon_urlstring | nullkohustuslik

    Ikooni URL (/v1/catalog/services/{service_id}/icon?v=… või paigalduse seadistatud väline aadress). null, kui ikooni ei ole.

  • idstring (uuid)kohustuslik
  • namestringkohustuslik
  • slugstringkohustuslik
  • websitestring | nullkohustuslik

    Veebisaidi URL (https://…) või null.

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

  • Retry-After

    Sekundite arv, mida oodata enne päringu kordamist.

  • RateLimit-Policy

    Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.

  • RateLimit

    Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).

  • X-RateLimit-Remaining

    Rangeima piirangu järgi järelejäänud päringud.

  • X-RateLimit-Reset

    Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← catalog · API teatmik