Oversikt
Impact-sluttbrukere (IEU-er) kan ønske å bruke API-er for å opprette segmenter.
Bare Impact-abonnementsadministratorer har muligheten til å opprette API-nøkler. De kan opprette API-nøkler ved å gå til Innstillinger > Integrasjoner . Hvis Integrasjoner- fanen ikke er tilgjengelig, er ikke API-et aktivert for abonnementet ditt. Ta kontakt med Impact for å spørre om tilgang til API-integrasjon.
Merk: Hvis du logger deg på kontoen din fra et annet sted enn app.impact.instructure.com, må du oppdatere URL-ene til endepunktet slik at de samsvarer med det tilpassede vertsnavnet.
Oppretting av API-segment
GET Liste over alle segmenter
List opp alle segmentdefinisjoner. Mulighet for å filtrere etter segmenter opprettet via API.
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Spørreparametere |
| createdByApi (valgfritt, standardverdien er usann) | Sann: returner kun segmenter opprettet via API Usann: returner alle segmenter |
| Svar |
| 200 OK | [ { "opprettet av bruker": {…}, "opprettetDag":<dato/klokkeslett>, "sist oppdatert av bruker": { … }, "sist oppdatert":<dato/klokkeslett>, "slag": "Segment", "id": "<segment-ID>", "navn": "Testsegment 1", "opprettet av Api": sant, "definisjon": { … }, "rørledning": [ … ], "avhengigeMetadata": [...] "erFokusGruppe": usann }, { "opprettet av bruker": {…}, "opprettetDag": <dato/klokkeslett>, "sist oppdatert av bruker": { … }, "sist oppdatert":<dato/klokkeslett>, "slag": "Segment", "id": "<segment-ID>", "navn": "Testsegment 2", "opprettet av Api": usann, "definisjon": { … }, "rørledning": [ … ], "avhengigeMetadata": [...] "isFocusGroup": usann }, … ] |
| 500 Intern serverfeil | «Det oppsto en uventet feilstreng» |
HENT segment etter ID
Hent en segmentdefinisjon etter ID
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Banevariabler |
| segment-ID | streng |
| Svar |
| 200 OK | { "opprettet av bruker": {…}, "opprettetDag": <dato/klokkeslett>, "sist oppdatert av bruker": { … }, "sist oppdatert": <dato/klokkeslett>, "slag": "Segment", "id": "<segment-ID>", "navn": "Testsegment", "opprettet av Api": sant, "definisjon": { … }, "rørledning": [ … ], "avhengigeMetadata": [...] "isFocusGroup": usann } |
| 404 Ikke funnet | Finner ikke segmentet med den oppgitte ID-en |
| 500 Intern serverfeil | «Det oppsto en uventet feilstreng» |
STOLPEOpprett segment
Opprett et segment fra en liste over besøkende.
{ "navn": "<SEGMENTNAVN>", "besøkende": [ "besøkende1", "besøkende2", "besøkende3", ... "besøkendeN" ] } |
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Forespørselstekst |
| navn (obligatorisk) | streng |
| besøkende (obligatorisk) | Liste over besøks-ID-er som strenger. Støtter opptil 10 millioner besøks-ID-er |
PUT- oppdateringssegment
Oppdater et segment
{ "navn": "<SEGMENTNAVN>", "besøkende": [ "besøkende1", "besøkende2", "besøkende3", ... "besøkende" ] } |
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Banevariabler |
| segment-ID | streng |
| Forespørselstekst |
| Navn (valgfritt) | Streng |
| Besøkende | Liste over besøks-ID-er som strenger. Støtter opptil 10 millioner besøks-ID-er. |
Merk: Minst én verdi er påkrevd. Enhver verdi som oppgis vil bli oppdatert og overskrive den forrige verdien. Enhver verdi som ikke oppgis, vil forbli uendret.
| Svar |
| 200 OK | { "segmentId": <segmentId>, "statusURL": " https://app.pendo.io/api/v1/segment/:segmentId/status " } |
| 400 Ugyldig forespørsel | «Feilmelding som streng» |
| 404 Ikke funnet | Finner ikke segmentet med den oppgitte ID-en |
| 500 Intern serverfeil | «Det oppsto en uventet feilstreng» |
SLETT Slett segment
Slett et segment
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Banevariabler |
| segment-ID | streng |
| Svar |
| 204 Intet innhold | «» |
| 400 Ugyldig forespørsel | «Feilmelding som streng» |
| 404 Ikke funnet | Finner ikke segmentet med den oppgitte ID-en |
| 500 Intern serverfeil | «Det oppsto en uventet feilstreng» |
BLISegmentstatus
Hent statusen til et segment. Segmentstatusen vil være gyldig i opptil fire timer etter at behandlingen er fullført.
| Forespørselshoder |
| Innholdstype | applikasjon/json |
| x-pendo-integrasjonsnøkkel | <PENDO_INTEGRATION_KEY> |
| Banevariabler |
| segment-ID | streng |
| Svar |
| 200 OK | { } |
| 400 Ugyldig forespørsel | «Feilmelding som streng» |
| 404 Ikke funnet | Finner ikke segmentet med den oppgitte ID-en |
| 500 Intern serverfeil | «Det oppsto en uventet feilstreng» |
Adgang
Endepunktene for å opprette, oppdatere og slette segmenter krever API-tilgang via en integrasjonsnøkkel med skrivetilgang.
Integrasjonsnøkler
Etter at IEU API-tilgang er gitt, kan IEU-abonnementene få tilgang til integrasjonsnøkkelen sin via innstillingssiden.
Her er brukerflyten som administratoren av FI-abonnementet skal gå gjennom:
- API-nøkler administreres fra Innstillinger > Integrasjoner
- De vil generere en integrasjonsnøkkel ved å oppgi en beskrivelse. De må tillate skrivetilgang.Hvis et token ikke gis skrivetilgang, vil ethvert POST/PUT/DELETE-endepunkt returnere en 403 Forbidden.
- På det tidspunktet kan de kopiere integrasjonsnøkkelen som er oppgitt, inn i Smart.
- De kan gå tilbake til denne skjermen for å legge til flere nøkler eller slette eksisterende nøkler.
Behandling
Segmenter opprettes umiddelbart, men det tar ekstra tid å legge til besøkende i segmentet.
Besøkende legges til i segmenter via en asynkron jobb. Segmentene behandles ett om gangen (per abonnement).
Zoom inn
Et segment vil gå gjennom tre forskjellige statuser mens det legger til besøkende.
I påvente av:Segmentet venter i kø på å bli behandlet. I denne tilstanden betjener segmentet fortsatt den forrige besøkslisten.
Framgang:Segmentet har startet behandlingen. I denne tilstanden vil listen over besøkende i segmentet slettes.
Besøks-ID-er blir renset (fjern innledende og etterfølgende mellomrom) og normalisert (hvis «Hvis abonnementsflagget «Konverter besøks-ID-er til små bokstaver» er aktivert, bruker vi små bokstaver for alle besøks-ID-er som er oppgitt).
Hvis et element ikke består valideringen, stoppes behandlingen, statusen endres til «feil» og det vises en feilmelding. Besøkslisten forblir tom.
Fullfør:Behandlingen er fullført. Segmentet for besøkende gjenspeiler besøkendelisten fra CSV-filen. Den kvalifiserte besøkendelisten i brukergrensesnittet viser bare besøkende vi har mottatt data for, og som ikke er på ekskluderingslisten.
Feil:Det oppsto en feil under behandlingen.
Vent på det
Behandlingen skal starte nesten umiddelbart, men segmenter behandles bare én om gangen, så hvis flere oppdateringer sendes samtidig, vil de bli liggende i køen. Når et segment begynner å behandles, forventer vi ikke at det tar mer enn 15 minutter. Behandlingstiden vil variere avhengig av antall besøkende.
Synkroniseringsfrekvens
Disse endepunktene regnes som endepunkter for masseoppretting/-oppdatering. De bør brukes til automatiserte oppdateringer, for eksempel når en bruker klikker på en synkroniseringsknapp, eller regelmessige oppdateringer hver natt. De bør ikke brukes til strømming av oppdateringer hvert minutt (🔜enkelt-/småbatchoppdateringer kommer snart!).
Vanlige spørsmål
Hva skjer hvis API-integrasjonsnøkkelen blir tilbakekalt?
Alle API-er vil returnere en 403 Forbudt
Hva skjer hvis API-integrasjonsnøkkelen ikke får skrivetilgang?
POST/PUT/DELETE-endepunktene vil returnere en 403 Forbidden-feil
Hva skjer hvis et segment slettes og vi prøver å oppdatere?
PUT-forespørselen returnerer med feilen 404 Ikke funnet
Hva skjer hvis CSV-filen inneholder ugyldige besøks-ID-er?
Ugyldige besøks-ID-er inkluderer strenger som er for lange (større enn 128 tegn) eller strenger som inneholder ugyldige tegn. API-forespørselen skal mislykkes hvis den mottar ugyldige besøks-ID-er. Den vil returnere en 400-statuskode med en beskrivende feilmelding.
Hva skjer hvis det oppstår en feil under behandlingen?
Hvis det oppstår en uventet feil under behandlingen, prøver vi på nytt. Hvis alle forsøkene har mislyktes, returnerer statusen «feil», og segmentet forblir tomt.