PATCH/v1/sources/{source_id}/settings

Opdatér kildens indstillinger

update_source_settings

Angiver tilladelsestilstanden (own bruger samlingens tilladelser; mirror henter synligheden fra kilden, og den kan ikke ændres manuelt), de valgte mapper, mappen i samlingen til kort og hvor længe kort bevares, efter at kilden er slettet; i webapplikationen også forbindelsen og objekttyperne. Kræver SOURCE_MANAGE; en ændring af tilladelsestilstanden kræver også COLLECTION_MANAGE_PERMISSIONS på kildens samling. Når tilladelsestilstanden eller objekttyperne ændres, starter en fuld synkronisering. Tilføjet i 1.9.0. Med en API-nøgle for organisationen (fra 1.62.0) er kun en brugerdefineret kilde (kind: custom) tilgængelig: nøglen skal have rollen admin og scopet admin. Enhver anden type returnerer 400 sources.kind_not_allowed_for_key; connectorer, der logger ind hos udbyderen, sættes op i browseren. Connectorernes felter vises ikke i den offentlige specifikation.

Autentificering

Send en API-nøgle i headeren Authorization: Authorization: Bearer <nøgle>.

Stiparametre

source_idintegerpåkrævet

Headerparametre

X-View-Asstring
Kun for API-nøgler med rollen admin. Udfører anmodningen som dataprofilen <profile>[:viewer|verifier|editor], fx employee:viewer. Installationsnøglen kan ikke bruge denne header (403).
Idempotency-Keystring
Nøgle til et sikkert nyt forsøg på en skrivning: 1 til 255 printbare ASCII-tegn; en UUID v4 pr. logisk operation anbefales. Et nyt forsøg med samme nøgle inden for 24 timer udfører ikke operationen igen: det returnerer det gemte svar (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøgle med en anden metode, sti, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første anmodning stadig kører, 409 api.idempotency_in_progress med Retry-After: 1. Efter et 5xx- eller 429-svar frigives nøglen, og et nyt forsøg udfører operationen igen. Nøglen gælder for organisationen og den kaldende part (API-nøgle, bruger eller nøgle til en brugerdefineret kilde).
length ≥ 1, length ≤ 255

Cookieparametre

kb_view_asstring
Cookie for tilstanden »View as« i en session. POST /auth/view-as sætter den, og DELETE /auth/view-as fjerner den.

Anmodningens brødtekst

application/json

Objekt: SourceSettingsUpdate

permissions_modestring | null
Tilladte værdier: ownmirrornull
retention_daysinteger | null
Hvor mange dage kortene bevares, efter at kilden er slettet; 0 fjerner dem med det samme.
≥ 0, ≤ 3650
rootsarray of string | null
Kildens valgte mapper (API 1.53.0); for en brugerdefineret kilde dokumenternes mappestier.
folder_idstring | null
Mappe i samlingen (en tom streng betyder samlingens rod).
folder_modestring | null
Tilladte værdier: flatmirrornull

Svar

200Vellykket svar

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.
Idempotency-Replayed
true betyder, at svaret blev afspillet igen fra det gemte svar for denne Idempotency-Key: operationen blev ikke udført igen.

application/json

Objekt: SourceStatus

source_idintegerpåkrævet
kindSourceKindpåkrævet
namestringpåkrævet
permissions_modestringpåkrævet
Tilladte værdier: ownmirror
retention_daysintegerpåkrævet
fetchedintegerpåkrævet
indexedintegerpåkrævet
failedintegerpåkrævet
removedintegerpåkrævet
pendingintegerpåkrævet
object_typesarray of SourceObjectTypepåkrævet
runningobject | nullpåkrævet
Den igangværende kørsel (started_at, stage, done, total, errors, triggered_by, run_id) eller null.
Felter
- started_atnumber
- stagestring
- doneinteger
- totalinteger
- errorsinteger
- triggered_bystring | null
- run_idstring | null
last_statusstring | nullpåkrævet
last_errorstring | nullpåkrævet
last_sync_atstring (date-time) | nullpåkrævet

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

404Objektet findes ikke eller er ikke tilgængeligt for dig. API’et bekræfter ikke, at et begrænset objekt findes.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

Retry-After
Antal sekunder, du skal vente, før du prøver anmodningen igen.
RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← sources · API-reference

curl -X PATCH 'https://api.sursa.com/v1/sources/1/settings' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"permissions_mode":"own","retention_days":0,"roots":["string"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Afprøv

API-nøgle

Nøglen gemmes kun i denne fanes hukommelse og sendes kun til https://api.sursa.com.

Anmodningerne udføres på din organisations rigtige data.

X-View-As header

source_id path *

Idempotency-Key header

Idempotency-Key

Er feltet tomt, genereres en ny nøgle for hver anmodning.

Anmodningens brødtekst (JSON)