Søke etter dialoger

Hvordan søke etter og filtrere dialoger i Dialogporten

Introduksjon

Denne veiledningen viser hvordan du søker etter dialoger i Dialogporten. Sluttbruker-API-et støtter både REST og GraphQL. Tjenesteeier-API-et støtter REST-søk med ekstra filtre som er nyttige når du administrerer dialoger og sluttbrukerkontekst.

Merk at datastrukturen som returneres i søk er forskjellig fra den som returneres fra detaljendepunktet; mer informasjon om dialogen og hvilken tilgang den autoriserte brukeren har til ulike deler av den er bare tilgjengelig i detaljvisningen.

Grunnleggende steg (REST, sluttbruker)

1. Autentiser som sluttbruker
2. Finn partene som den autentiserte sluttbrukeren er autorisert til å representere
3. Utfør en GET-forespørsel til /api/v1/enduser/dialogs, og oppgi query-parametere i henhold til tabellen nedenfor:

• Alle parametere av ulike typer kombineres med OG, dvs. hvis du oppgir party og status, returneres bare dialoger med den oppgitte statusen som eies av den oppgitte parten.
• Når flere verdier støttes for samme parameter, kombineres disse med ELLER, dvs. hvis du oppgir to status-parametere, returneres dialoger som har en av disse verdiene.
• org-parametere må være tjenesteeierkoder slik de er definert i den globale altinn-orgs.json, f.eks. digdir eller skd.
• party-parametere må ha ett av følgende formater
  • urn:altinn:person:identifier-no:<11 siffer fødselsnummer>
  • urn:altinn:organization:identifier-no:<9 siffer organisasjonsnummer>
• serviceResource-parametere må referere til en ressurs i Resource Registry og bruke følgende format:
  • urn:altinn:resource:<identifier>

Returnert informasjon

Dette vil returnere en samling av dialoger, som inneholder et delsett av informasjonen som returneres fra endepunktet for dialogdetaljer. Avhengig av søkeparametere og tilgangen til den autentiserte brukeren kan denne listen være tom.

Hvis ugyldige søkeparametere oppgis, returnerer API-et 400 Bad Request og et svar som forklarer hvilke feil som ble funnet. Dette svaret følger standardformatet ProblemDetails.

Paginering

Søke-API-et er paginert ved hjelp av fortsettelsestoken, se parameteren limit ovenfor. Hvis det finnes flere sider som kan hentes, vil egenskapen hasNextPage være satt til true, og egenskapen continuationToken vil være satt til en verdi som skal brukes for å hente neste side. For å hente neste side oppgir du denne verdien som query-parameteren continuationToken. Dette bevarer sorteringen og unngår å miste elementer eller hente dem to ganger. Dette bør gjentas så lenge hasNextPage er true.

Sortering

Sortering kan utføres på følgende kolonner:

• ContentUpdatedAt
• CreatedAt
• UpdatedAt
• DueAt

contentupdatedat er den anbefalte kolonnen når du sorterer dialoger for innboks-lignende visninger og for best ytelse.

Hvis ingen eksplisitt sortering oppgis, er standardrekkefølgen contentupdatedat_desc.

Eksempler

Dette er eksempelverdier som kan oppgis i query-parameteren OrderBy.

• contentupdatedat_desc
• createdat
• createdat_asc
• dueat_asc

Gjeldende sortering finner du i samlingsmodellen, ved siden av feltene continuationToken og hasNextPage. I REST er sorteringen også bygget inn i continuationToken, så det er tilstrekkelig å oppgi fortsettelsestokenet alene for å bevare sorteringen.

Grunnleggende steg (REST, tjenesteeier)

1. Autentiser som tjenesteeier
2. Utfør en GET-forespørsel til /api/v1/serviceowner/dialogs, og oppgi query-parametere i henhold til tabellen nedenfor:

Søkeendepunktet for tjenesteeier støtter de samme grunnleggende dialogfiltrene som sluttbrukerendepunktet, og eksponerer i tillegg filtre for:

• serviceOwnerLabels, der alle oppgitte etiketter må matche
• serviceOwnerLabels med *-suffiks for prefikssøk, for eksempel finance*
• visibleAfter og visibleBefore

Hvis du trenger å hente revisjoner og systemetiketter for sluttbrukerkontekst uten hele dialogsøkeresultatet, se referansen for systemetiketter, som dokumenterer det dedikerte endepunktet /api/v1/serviceowner/dialogs/endusercontext.

Grunnleggende steg (GraphQL, sluttbruker)

GraphQL eksponerer søkeoperasjonen for sluttbruker som searchDialogs. En typisk flyt er:

1. Autentiser som sluttbruker
2. Bruk getParties for å finne parti-URN-ene du kan søke på
3. Kall searchDialogs

Eksempel:

query SearchDialogs($party: [String!]) {
  searchDialogs(
    input: {
      party: $party
      limit: 20
      orderBy: [{ contentUpdatedAt: DESC }]
    }
  ) {
    items {
      id
      party
      status
      process
      createdAt
      updatedAt
      contentUpdatedAt
      endUserContext {
        revision
        systemLabels
      }
    }
    hasNextPage
    continuationToken
    orderBy {
      createdAt
      updatedAt
      dueAt
      contentUpdatedAt
    }
    errors {
      message
    }
  }
}

GraphQL-input støtter de samme implementerte filtrene for sluttbruker som REST-endepunktet, inkludert:

• serviceResource
• party
• status
• process
• systemLabel
• excludeApiOnly
• isContentSeen
• search
• searchLanguageCode

De samme underliggende valideringsreglene gjelder som i REST. Spesielt må minst én av party eller serviceResource oppgis.

Aksepterte språk

GraphQL bruker den samme Accept-Language-headeren som REST-API-et. Hvis den er oppgitt, bruker Dialogporten den headeren når lokaliserte innholdsverdier velges og sorteres i svaret.

Paginering

Paginering i GraphQL bruker feltene continuationToken, hasNextPage og orderBy i payloaden.

• Bruk det returnerte continuationToken for å hente neste side
• Bruk den samme orderBy på nytt når du sender neste forespørsel
• Hvis continuationToken er satt, må også orderBy være satt