Etablere en lokal kopi av Person‑API

Denne siden viser de anbefalte stegene for å opprette en lokal kopi av data fra Person‑API, og holde den oppdatert ved hjelp av hendelses‑feed‑en.

Kort sagt kan en lokal kopi opprettes med følgende fremgangsmåte:

1. Hent sekvens‑nummeret for den siste hendelsen ved å kalle event/latest‑endepunktet. Lagre dette sekvens‑nummeret for senere bruk.
2. Kall search/paged-match-list‑endepunktet uten parametere. Dette gir deg mulighet til å paginere gjennom hele befolkningen i Person‑API; hver side inneholder en liste med person‑referanser (person‑ID‑er).
3. For hver side med person‑ID‑er som du får fra search/paged-match-list, bruk person/bulk-by-id‑endepunktet for å hente de komplette person‑dokumentene som svarer til disse ID‑ene.
4. Begynn å behandle hendelses‑feed‑en fra sekvens‑nummeret du identifiserte i steg 1. Merk at sekvens‑nummeret vil ha økt mens du har lest gjennom hele befolkningen. Når du har kommet til den nyeste hendelsen, vil den lokale kopien være oppdatert og klar til bruk.

Steg 1: Lagre det nyeste sekvens‑nummeret

Når informasjon om en person endres i Person‑API, blir det generert en hendelse i hendelses‑feed‑en. Ved å kalle event/latest‑endepunktet får du den siste hendelsen i feed‑en. Svaret inneholder:

• sekvens‑nummeret for den siste hendelsen,
• en referanse til personen som ble oppdatert, og
• hendelsestypen som viser hvilken informasjon som har endret seg.

Et eksempel på resultatet ser slik ut:

{
  "sequenceNumber": "11618128",
  "personId": "2c37dae1-a161-433f-95b3-8a547e82caa5",
  "eventType": "ChangeInResidentialAddress"
}

I dette steget er det eneste vi trenger å gjøre å hente ut sekvensnummeret for den siste hendelsen og lagre det, slik at vi senere kan begynne å konsumere hendelser fra dette sekvensnummeret når den lokale kopien er etablert.

Steg 2 og 3: Trekke ut befolkningen

Steg 2 og 3 utføres sammen, og målet er å hente data for hele befolkningen ved å finne en referanse til hver unik person i registeret og laste ned den aktuelle informasjonen. Det er også mulig å begrense dette steget til en delmengde av befolkningen, avhengig av hvilke parametere du bruker for søket med search/paged-match-list.

search/paged-match-list‑endepunktet er laget for å søke i store person‑sett, men støtter også paginering gjennom hele befolkningen. Når du kaller search/paged-match-list uten noen parametere, matches hele befolkningen, og du kan paginere gjennom sider som inneholder referanser til hver unik person i Person‑API. Hvis du kun er interessert i en del av befolkningen, kan du konfigurere søket etter dine kriterier – for eksempel ekskludere personer med status Deceased, Discontinued, Inactive, osv., avhengig av ditt brukstilfelle.

For hvordan du skal håndtere personer som er registrert som opphørt i Person‑API, se opphørte personer.

Anbefaling:

• Sett pageSize til maks (10 000) når du gjør forespørsler til search/paged-match-list.
• Når du ber om neste side, sett indexOffset til endIndex + 1 fra forrige resultat.

Se API‑dokumentasjonen for mer detaljert beskrivelse av endepunktet.

Resultatet fra search/paged-match-list inneholder ikke persondokumenter, men en liste med person‑ID‑referanser. Dataene for hver person må lastes ned i bulk ved å bruke person/bulk-by-id‑endepunktet og sende inn en liste med person‑ID‑er. person/bulk-by-id støtter opptil 100 ID‑er per forespørsel, men du kan sende flere parallelle forespørsler for å hente data raskere. Når du bruker person/bulk-by-id, må du også angi et informasjonsfilter og om du vil ha historikk i persondokumentet (f.eks. historiske identifikatorer eller adresser).

Når du har paginert gjennom alle sider og lastet ned data for alle unike personer, er den lokale kopien etablert.

Steg 4: Holde den lokale kopien oppdatert

For å holde den lokale kopien oppdatert med endringer fra Person‑API, må du konsumere hendelses‑feed‑en og oppdatere informasjonen for personer som har endret seg.

1. Kall event‑endepunktet og angi det laveste sekvens‑nummeret du vil ha med i svaret. Svaret er en liste med hendelser (opptil 1 000) som følger i feed‑en.
2. Fortsett å konsumere hendelser som har et høyere sekvens‑nummer enn det du lagret i steg 1. Kall event med lagret sekvens‑nummer + 1; svaret vil inneholde alle hendelser som har skjedd mens du hentet hele befolkningen.
3. For hver ny hendelse, last ned en ny versjon av persondokumentet for den aktuelle personId ved å bruke person/get-by-id eller person/bulk-by-id.
4. Lagre alltid ditt sist behandlede sekvens‑nummer etter hver batch med hendelser. På den måten vet du hvor du er i strømmen.

Vi anbefaler å sjekke etter nye hendelser ofte (f.eks. hvert 1, 5, 15 eller 30 minutt) istedenfor å gjøre en stor synkronisering én gang om dagen. Dette gir en mer oppdatert og konsistent lokal kopi.