WP REST API Henter data

I de tidligere delene av serien har vi sett på hva WP REST API er, og hvordan det kan hjelpe oss med å bygge bedre applikasjoner ved hjelp av WordPress-bakenden. 

Da så vi på to måter å sette opp godkjenning på serveren for å generere godkjente forespørsler. Den første er den grunnleggende autentiseringsmetoden, som er nyttig i utviklingsmiljøer og muliggjør rask prototyping, da det ikke krever mye tid å sette opp. Den andre metoden for godkjenning er OAuth 1.0a, som anbefales for produksjonsmiljøer, da den er mye sikrere enn den grunnleggende godkjenningsmetoden.

Nå som vi har lært å konfigurere godkjenning, er vi klare til å generere godkjente forespørsler for å frigjøre full kraft i WP REST API. Vi vil bruke grunnleggende godkjenning gjennom denne serien på grunn av brukervennlighet, men det anbefales at du bruker OAuth 1.0a-godkjenning, som følger med OAuth 1.0a-plugin, for produksjonsserverne.

I den nåværende delen av serien får vi vår aller første praktisk erfaring med pluginprogrammet WP REST API. Vi vil:

  • analysere strukturen av a  be om
  • sjekk ut hvordan ALTERNATIVER Be om selvdokumenter API
  • send forespørsler til serveren for datainnhenting
  • analyser serverresponsen som inneholder egenskaper, skjema og koblinger

Så la oss begynne med å analysere strukturen av en enkel  be om.

Anatomi av a Be om

Før vi dykker inn i detaljene for å hente data med WP REST API, må vi gjøre oss kjent med syntaksen til en forespørsel som sendes til serveren. Dette vil legge et solid grunnlag for våre fremtidige samspill med WP REST API.

Vurder følgende forespørsel sendt til serveren:

$ GET http: // localserver / wp-json / wp / v2 / innlegg

Den type forespørsel vi sender er -ett av seks HTTP-verb som vi så på i den første delen av denne serien. EN  forespørsel brukes til å hente data fra serveren. Derfor, når den utføres på serveren, henter ovennevnte forespørsel en samling av alle postobjekter i form av JSON-data.

Med tanke på forespørselen URI, kan vi bryte den inn i følgende deler:

  • http: // Local /: Nettadressen til min lokale utviklingsserver. Det kan være en hvilken som helst nettadresse, avhengig av hvor WordPress-installasjonen din er plassert.
  • / Wp-.json: Det er sluttpunkts prefikset for WP REST API.
  • / wp: Navnet på WP REST API-plugin-modulen.
  • / v2: Det er versjonen av WP REST API-plugin.
  • / innlegg: Det er ressursen som vi vil hente fra serveren.

Navneområdet forhindrer overstyring som kan oppstå når du kjører flere pluginprogrammer med hver som gir sitt eget abstraksjonslag for RESTful API. Derfor arbeider hver abstraksjon i sin egen grense uten å påvirke metodene og egenskapene som tilhører en annen abstraksjon.

Navneområdet og versjonen var ikke til stede i den eldre versjon 1.2 av plugin. Så i den eldre versjonen vil ovennevnte forespørsel være slik:

$ GET http: // localserver / wp-json / innlegg

Men vi snakker ikke om bakoverkompatibilitet her. Hvis du vil lære om alle endringene som skjedde mellom versjon 1.x og 2.x, kan du finne dem på den offisielle siden.

I tillegg til å hente en samling ressurser (innlegg) ved hjelp av URI-filen ovenfor, kan vi også hente en bestemt ressurs ved å nevne sin ID:

$ GET / wp / v2 / innlegg / 100

Ovennevnte forespørsel vil returnere et innleggsobjekt som det ser ned for en postressurs som har en ID på 100.

Andre ganger må vi også søke etter innlegg som oppfyller noen spesifikke kriterier. Til dette formål gir WP REST API en måte å bruke filter[] syntaks:

$ GET / wp / v2 / innlegg? Filter [cat] = 1

Ved å sende ovennevnte forespørsel kan vi hente alle innleggene som tilhører en kategori ID 1. Filtersyntaxen kan være spesielt nyttig når du spør etter innlegg eller navigerer mellom forskjellige ressurser, f.eks. innlegg og kategorier, ved hjelp av deres relasjoner.

Til slutt, når du arbeider med argumenter som tar arrays som input i filter[] syntaks, kan vi legge til et tomt sett med firkantede parentes for å uttrykke arrays slik:

$ GET / wp / v2 / innlegg? Filter [category__and] [] = 1 & filter [category__and] [] = 2

Ovennevnte syntaks er ekvivalent med følgende WP_Query ():

 array (1, 2)));

Derfor er det ovenfor  forespørsel vil hente en liste over innlegg som tilhører begge kategoriene som har en ID på 1 og 2. Den samme syntaksen kan også brukes til arrayargumenter som har mer enn to elementer. Vær oppmerksom på at bruken av category__and parameteren krever brukerautentisering med edit_posts privilegier.

Vi vil se på filter[] syntaks mer detaljert i et senere avsnitt.

Nå som vi har lært om formatering a  forespørsel og gi sine parametre, er det på tide å se på ALTERNATIVER be om. en ALTERNATIVER forespørsel gjør det enkelt å navigere gjennom API og faktisk fungerer som en selvdokumenterende måte å gjøre APIen mer tilgjengelig ved å dokumentere alle tilgjengelige HTTP-metoder på et sluttpunkt, og i sin tur argumentene de støtter.

Navigere gjennom API ved hjelp av ALTERNATIVER Be om

Som nevnt før, ble ALTERNATIVER forespørsel kan være svært nyttig i å utforske API. Den nevner alle endepunktene som tilhører en bestemt rute og gir en liste over parametere disse endepunktene støtter CRUD-operasjoner.

La oss sende en ALTERNATIVER forespørsel til / WP / v2 / innlegg rute for å sjekke hvilke sluttpunkter det støtter og hvilke parametere vi kan passere langs  forespørsel om å spørre data:

$ curl -X OPTIONS wp / v2 / innlegg

Jeg har brukt cURL til å sende ovennevnte forespørsel, men du kan bruke et hvilket som helst verktøy av ditt valg, inkludert Postman. Pass på å ta med hele banen til den ovennevnte ruten, inkludert banen til serveren din.

"namespace": "wp / v2", "metoder": [...], "endepunkter": [...], "skjema": ..., "_links": ...

Ovennevnte ALTERNATIVER forespørsel til / WP / v2 / innlegg rute returnerer data i JSON-formatet som inneholder fem egenskaper:

  1. namespace
  2. fremgangsmåter
  3. endepunkter
  4. skjema
  5. _links
"namespace": "wp / v2", ...

De namespace eiendom identifiserer navneområdet for gjeldende plugin. I vårt tilfelle er det wp / v2, betegner versjon 2 av WP REST API. Vi har allerede sett på navneområdet og formålet som det tjener i forrige del.

... "metoder": ["GET", "POST"], ...

De fremgangsmåter Egenskapen inneholder en rekke av alle metodene som støttes av den nåværende ruten. Ved å se svaret på ovennevnte forespørsel, er det klart at / WP / v2 / innlegg ruten støtter to metoder, nemlig  og POST. Det betyr at vi kan bruke / WP / v2 / innlegg rute for å hente innlegg, samt opprette et nytt innlegg. Vi skal håndtere POST metode i neste del av denne serien, så la oss bare fokusere på  metode for tiden.

Den neste eiendommen-endepunkter-inneholder en rekke støttede endepunkter for den nåværende ruten. Denne eiendommen er direkte knyttet til det tidligere nevnte fremgangsmåter Egenskapen som den viser sluttpunkter for de støttede metodene.

... "endepunkter": ["metoder": ["GET"], "args": ..., "metoder": ["POST"], "args": ..., ...

De endepunkter Egenskapen inneholder objektverdier som i sin tur inneholder to egenskaper, nemlig fremgangsmåter og args. De fremgangsmåter Egenskapen inneholder en rekke HTTP-metoder, og den neste args Egenskapen inneholder alle de støttede argumentene for disse metodene. Dette er argumentene som vi sender sammen med forespørselen i form av URI-parametere.

Ser på argumentene som støttes av  metode, vi kommer over ni argumenter som inkluderer kontekstsideper side, etc. Disse argumentobjektene inneholder to egenskaper, nødvendig og misligholde. De nødvendig Egenskapen indikerer om argumentet kreves, og misligholde Egenskapen representerer standardverdien av argumentet.

"metoder": ["GET"], "args": "kontekst": "nødvendig": falsk, "standard": "visning", "side": "påkrevd": falsk, "standard" 1, "per_page": "required": false, "default": 10, "filter": "required": false

De skjema Egenskapen i det returnerte svaret dokumenterer alle egenskapene for gjeldende ressurs. Skjemaet definerer en struktur for data i JSON-formatet. Skjemaformatet som brukes i WP REST API er basert på utkast 4 i JSON-skjema spesifikasjonene.

Den siste _links Egenskapen inneholder en rekke objekter som inneholder koblingene til tilknyttede ressurser. Nøkkelen i objektet angir forholdstypen (f.eks. forfatter, samling, selv-kommentarer, etc.), med sin verdi som lenken til den tilknyttede ressursen. Denne koblingsstandarden er basert på HAL (Hypertext Application Language). Du kan finne mer om HAL ved å lese spesifikasjonene som er skrevet av Mike Kelley.

På samme måte kan vi sende en ALTERNATIVER Forespørsel til andre ruter, inkludert de av brukere, kommentarer, media, sider, etc., for å sjekke støttede metoder og argumenter. ALTERNATIVER forespørsler er din beste venn når du arbeider med WP REST API.

WP REST API gir enda en annen måte å vurdere API-tilgjengeligheten ved å sende en  forespørsel til / Wp-.json indeksrute. Dette vil liste alle ruter og deres endepunkter sammen med deres støttede metoder og argumenter.

$ curl -X GET http: // wordpress-server / wp-json

Ovennevnte forespørsel vil returnere et responsobjekt som inneholder en ruteegenskap som følger:


Denne funksjonen er enormt kraftig fordi den viser alle rutene og deres støttede metoder og argumenter, og eliminerer dermed behovet for at alle disse skal dokumenteres eksternt. Vi vil referere til dette responsobjektet når vi utfører CRUD-operasjoner på forskjellige ressurser.

Etter å ha sett på alternativene våre for å utforske API, la oss nå begynne å jobbe med WP REST API for å hente data fra serveren.

Arbeide med innlegg

Vi har nå kjent oss med ALTERNATIVER forespørsel, som er en selvdokumenterende måte å vurdere API-tilgjengeligheten til. Vi så også på hvordan det viser støttede metoder og argumenter for en gitt rute. Ved hjelp av denne kunnskapen er vi nå klar til å hente forskjellige ressurser fra serveren ved hjelp av WP REST API.

Den ressursen vi skal begynne med, er innlegg ressurs, siden det er hovedblokken til WordPress. Vi tar hånd om å hente innlegg ved hjelp av forskjellige filtre. Ved å bruke denne kunnskapen, vil du kunne søke etter innlegg ved hjelp av WP REST API, akkurat som du gjør med WP_Query () klassen.

Gjennom hele denne serien har vi jobbet med innlegg ressurs for å demonstrere eksempelforespørsler og deres svar, og vi vet allerede hvordan å hente postsamlingen og et enkelt innlegg etter sin ID. Så vi vil ikke dekke det igjen. I stedet vil vi se på noen mer avanserte måter å hente innlegg ved hjelp av toppnivåparametrene og filter[] syntaks.

Arbeide med toppnivåparametere

WP REST API avslører noen av de mest brukte søkevariablene for innlegg direkte på  endepunkt. Disse parametrene er:

  1. kontekst: Omfanget av forespørselen. Mulige verdier kan være utsiktembed eller redigere.
  2. side: Den nåværende siden av postsamlingen.
  3. per side: Totalt antall innlegg per side.
  4. Søke: Søkeforespørselen. Begrens resultatene til matchende streng.
  5. forfatter: Forfatter-ID. Brukes til å begrense resultater som tilhører en bestemt forfatter.
  6. utelukke: En rekke post-IDer for å ekskludere fra søkeresultatene.
  7. inkludere: Begrens resultatene til post-IDer angitt i denne gruppen.
  8. offset: Angi søkeresultatene med spesifisert nummer.
  9. rekkefølge: Ordren til samlingen. Kan enten være ASC eller desc.
  10. rekkefølge etter: Sortering av attributten til samlingen. Mulige verdier kan være idtittel eller slug.
  11. slug: Begrens resultatene til et innlegg som har en bestemt slug.
  12. status: Brukes til å begrense samlingen av innleggene som har en bestemt status.

De kontekst parameter brukes til å hente innlegg avhengig av omfanget vi jobber med. Hvis vi bare oppfører innlegg på en indeksside, så er vi gode til å gå med utsikt kontekst. Men hvis vi henter inn innlegg for å redigere dem, må vi bruke redigere kontekst:

$ GET / wp / v2 / innlegg? Context = edit

De redigere kontekstparameter introduserer en ekstra  felt i felt som tittelinnholdutdrag, etc. Verdien av dette  feltet kan echoed ut i redaktøren for redigering av innholdet.

Bruker redigere kontekst krever at du blir autentisert som bruker med edit_posts privilegier.

Ved hjelp av embed som verdien av kontekst parameter henter samlingen av innleggene med en minimal delmengde av egenskapene deres.

De andre parametrene nevnt ovenfor er ganske selvforklarende, og du kan leke med dem i HTTP-klienten din.

Disse var de grunnleggende parametrene som lar deg spørre innlegg basert på bestemte kriterier. For å begrense våre spørringsfunksjoner gir WP REST API den filter[] syntaks som støtter en delmengde av WP_Query () args.

Bruker filter[] syntax

I tillegg til å hente en samling innlegg ved hjelp av noen grunnleggende toppnivåparameter, avslører WP REST API noen av WP_Query () variabler ved hjelp av filter[] syntaks. Ved å bruke denne syntaksen, kan vi spørre innlegg på samme måte som vi gjør når vi jobber med WP_Query () klasse.

Paginasjonsparametere er de viktigste av alle filtrene, da de brukes mye på postlistingssidene. Paginasjonsparametrene lar oss vise et bestemt antall innlegg per side og navigere til et bestemt antall sider som inneholder innlegg.

Som standard a  forespørsel henter en samling på 10 innlegg per side. La oss se hvordan vi kan sende inn en  Be om å hente bare fem innlegg per side:

$ GET / wp / v2 / innlegg? Filter [posts_per_page] = 5

Ovenstående forespørsel bruker posts_per_page variabel som du kanskje er kjent med hvis du har jobbet med WP_Query ().

De paged parameter brukes i forbindelse med posts_per_page parameter, og det brukes til å navigere til et bestemt antall sider. Etter å ha hentet fem innlegg per side, ville vi gjøre følgende forespørsel om å navigere til den andre siden:

$ GET / wp / v2 / innlegg? Filter [posts_per_page] = 5 & filter [paged] = 2

De posts_per_page og paged filtre kan være svært nyttig når du arbeider for å bygge paginering på listingssider ved hjelp av WP REST API. Disse to parametrene er ekvivalente med per side og side parametere på toppnivå. Følgelig gjør følgende forespørsel det samme arbeidet som ovenfor:

$ GET / wp / v2 / innlegg? Per_page = 5 & side = 2

I tillegg til samlingen av innlegg returnerer ovennevnte forespørsel, returnerer serveren også et antall overskrifter med et svar som inneholder nyttig informasjon, inkludert totalt antall innlegg og antall sider. Disse verdiene finnes i X-WP-TotalPages og X-WP-Total svar overskrifter.

De X-WP-TotalPages og X-WP-Total svarhodene er ekstremt nyttige når du oppretter paginering ved hjelp av WP REST API, da de viser totalt antall sider og totalt antall innlegg.

Bortsett fra paginering filtre, den andre viktigste bruken av filter[] syntaks er å kunne søke innlegg etter datoene sine. For dette formålet, filter[] syntaksen støtter åtte parametere, det samme som i WP_Query () klasse:

  1. år: Det firesifrede året (for eksempel 2015 eller 2016)
  2. monthnum: Månedets nummer fra 1 til 12
  3. m: Sesifret årsmåned (for eksempel 201601)
  4. w: Uke av året fra 0 til 53
  5. dag: Månedens dag fra 1 til 31
  6. time: Dagens time fra 0 til 23
  7. minutt: Timetiden fra 0 til 60
  8. sekund: Den andre av minuttet fra 0 til 60

Så hvis vi ser etter innleggene publisert på datoen 2015-10-15 (åååå / mm / dd), kan dette oppnås ved følgende spørring:

$ GET / wp / v2 / innlegg? Filter [år] = 2015 og filter [måned] = 10 og filter [dag] = 15

En lignende spørring kan utarbeides ved hjelp av de ovennevnte parametrene hvis vi trenger å begrense søket til den nøyaktige timen og minuttet.

Vi har allerede sett i en tidligere del av denne veiledningen hvordan vi kunne hente innlegg som tilhører en bestemt kategori eller flere kategorier ved hjelp av filter [katt] og filter [category__and] parametre. Nå skal vi bruke filter [category__in] parameter for å vise innlegg som tilhører kategorier med et ID på 5 og 6:

$ GET / wp / v2 / innlegg? Filter [category__in] [] = 5 & filter [category__in] [] = 6

Ovennevnte forespørsel vil hente en liste over alle innleggene som tilhører kategorier med et ID på 5 og 6.

Den motsatte effekten kunne oppnås ved å bruke filter [category__not_in] parameter på følgende måte:

$ GET / wp / v2 / innlegg? Filter [category__not_in] [] = 5 & filter [category__not_in] [] = 6

Dette vil hente en liste over innlegg mens du unngår alle de innleggene som tilhører kategorier med en ID på enten 5 eller 6.

Mer kan skrives på ved hjelp av filter[] syntaks, men jeg vil ikke dekke alt det her. Du kan finne en liste over alle spørringsvariablene som støttes av filter[] syntaks i den offisielle dokumentasjonen av versjon 1 av plugin. En stor del av denne informasjonen er fortsatt gyldig med versjon 2 av WP REST API, men mangler fortsatt i enkelte områder. Når du skriver denne opplæringen, oppgir ikke den offisielle dokumentasjonen for versjon 2 noe om filter[] syntaks og spørringen vars den støtter, men vi kan håpe å se forbedringer i den offisielle dokumentasjonen i nær fremtid siden det er flere personer (inkludert meg selv) som bidrar til pluginutviklingen og dokumentasjonen.

Nå som vi har sett på forskjellige alternativer når du spørre innlegg ved hjelp av WP REST API, er vi klare til å fortsette vår reise og se på andre ressurser som støttes av WP REST API.

Arbeider med Postrevisjoner, Kategorier, Merker og Meta

Innleggsrevisjoner gir en måte å vise og gjenopprette redigeringer gjort på et innlegg. WP REST API gir deg mulighet til å se alle revisjoner av et innlegg ved å spørre / innlegg // revisjoner endepunkt. Derfor for et gitt innlegg med en ID på 10, kan alle revisjonene hentes ved å sende følgende forespørsel:

$ GET / wp / v2 / innlegg / 10 / revisjoner

Ovennevnte forespørsel vil returnere en matrise som inneholder revisjonsobjekter. Endringsobjektet inneholder en delmengde av egenskaper som finnes i postobjektet. Nedenfor er et eksempel revisjonsobjekt i Postman:

En spesifikk revisjon kan hentes gitt at vi kjenner sin id. Så en revisjon som har en ID på 2 med innlegg med en ID på 10 kan hentes av følgende objekt:

$ GET / wp / v2 / innlegg / 10 / revisjoner / 2

Ovennevnte forespørsel vil returnere et enkelt revisjonsobjekt.

Annet enn innleggsrevisjoner, kan kategorier for et bestemt innlegg bli hentet av følgende forespørsel:

$ GET / wp / v2 / kategorier? Post =

Og for kodene bruker vi følgende forespørsel:

$ GET / wp / v2 / tags? Post =

Med  å være ID av posten.

Hvis vi trenger å hente postmeta for innlegg som har en ID på 10, sender vi følgende forespørsel som en godkjent bruker:

$ GET / wp / v2 / innlegg / 10 / meta

Dette vil returnere en rekke metaobjekter.

Vær oppmerksom på at for å jobbe med post og side meta i WP REST API, må du ha følgesvenn plugin installert tilgjengelig på GitHub av WP REST API-teamet.

Arbeider med andre ressurser

Nå har vi fått et ganske solid grunnlag for å jobbe med WP REST API for å hente data. Vi har allerede sett på opsjonsforespørselen og hvordan det hjelper oss å utforske API-en uten behov for ekstern dokumentasjon. 

Du kan alltid sende en ALTERNATIVER Be om en bestemt ressurs og sjekk hvilke sluttpunkter og parametere den støtter. Hvis du trenger å liste alle rutene som WP REST API gir, kan du sende en  forespørsel til indeksendipunktet på / Wp-.json som vi lærte å gjøre i begynnelsen av denne opplæringen.

I betraktning av denne fordelen av selvdokumentasjon tror jeg ikke at vi ytterligere trenger å utforske hver enkelt ressurs i denne opplæringen, siden du nå kan gjøre det på egen hånd.

Hva skjer neste gang?

I denne lange opplæringen lærte vi å utforske API-en ved hjelp av OPTIONS-forespørselen, samt hente data fra serveren ved hjelp av WP REST API. Vi så bare på en håndfull ressurser, inkludert innlegg, postrevisjon og postmeta, da vi ikke kunne dekke alle støttede ressursene i bare én opplæring. Men du bør nå kunne utforske API på egen hånd ved hjelp av teknikkene vi lærte i denne opplæringen.

WordPress har en utrolig aktiv økonomi. Det er temaer, plugins, biblioteker og mange andre produkter som hjelper deg med å bygge opp ditt nettsted og prosjekt. Platformen med åpen kildekode gjør det også et godt alternativ som du kan forbedre programmeringsevnen din. Uansett, kan du se hva vi har tilgjengelig på Envato Marketplace.

I neste avdeling av denne serien vil vi lære å utføre de tre andre operasjonene til CRUD, dvs. opprette, oppdatere og slette ressurser. Så hold deg oppdatert ...