@harrasteblogi JUURI NYT
--:--

Tilaa uutiskirje

Saat tuoreimmat 10 uusinta artikkelia kerran viikossa sähköpostiisi.

Tilaa uutiskirje

WordPress oEmbed Provider -integraatiot

20.8.2026 | Artikkeleita, IT, Kotisivut, Nettisivut, Verkkokehitys, Verkkosivut, Verkkotyökalu, WordPress

WordPress
Facebook X WhatsApp

WordPress oEmbed Provider -integraatiot

WordPress oEmbed Provider -integraatiotWordPressin oEmbed-järjestelmä tekee ulkoisen sisällön upottamisesta yllättävän helppoa. Käyttäjä voi liittää esimerkiksi videon, kuvan tai muun palvelun URL-osoitteen editoriin, ja WordPress voi muuttaa sen automaattisesti upotetuksi sisällöksi.

Kehittäjän näkökulmasta kiinnostavampi puoli on kuitenkin toinen: WordPress voi toimia myös oEmbed Providerina.

Tällöin oma WordPress-sivusto ei ainoastaan kuluta muiden palveluiden upotuksia, vaan tarjoaa omaa sisältöään muiden järjestelmien upotettavaksi.

Mikä oEmbed on?

oEmbed on standardi, jonka avulla verkkosivu voi kysyä toiselta palvelulta:

”Miten tämä URL pitäisi upottaa sivulleni?”

Esimerkiksi käyttäjä voi antaa URL-osoitteen:

https://example.com/artikkeli/esimerkki

oEmbed-palvelu voi palauttaa tietoja, kuten:

  • otsikon
  • kuvauksen
  • tekijän
  • thumbnail-kuvan
  • sisällön tyypin
  • upotettavan HTML:n
  • leveyden
  • korkeuden

Näin ulkopuolisen sisällön näyttäminen ei vaadi jokaiselle palvelulle omaa käsin rakennettua integraatiota.

Consumer ja Provider

oEmbedissä on hyvä erottaa kaksi roolia.

Consumer käyttää muiden palveluiden oEmbed-tietoja.

Provider tarjoaa oman sisältönsä muiden järjestelmien käytettäväksi.

WordPress voi toimia molemmissa rooleissa.

Esimerkiksi:

WordPress → oEmbed Consumer → YouTube

tai:

Ulkoinen järjestelmä → oEmbed → WordPress

Jälkimmäisessä WordPress toimii Providerina.

Miten WordPress toimii oEmbed Providerina?

WordPressissä voidaan rekisteröidä oma oEmbed Provider esimerkiksi:

wp_oembed_add_provider(
’#https?://example\.com/.*#i’,
’https://example.com/wp-json/oembed/1.0/embed’,
true
);

Tällöin WordPressiin voidaan määrittää URL-malli, jota Provider käsittelee.

Kolmas parametri kertoo, käytetäänkö regex-kuviota URL-osoitteiden tunnistamiseen.

WordPressin oEmbed-endpoint

WordPress tarjoaa REST API:n kautta oEmbed-endpointin.

Tyypillinen muoto on:

/wp-json/oembed/1.0/embed

Sitä voidaan kutsua esimerkiksi URL-parametrilla:

https://example.com/wp-json/oembed/1.0/embed?url=https://example.com/artikkeli/esimerkki

Endpoint palauttaa oEmbed-standardin mukaista tietoa.

JSON-vastaus

oEmbed-endpoint voi palauttaa esimerkiksi:

{
”version”: ”1.0”,
”type”: ”rich”,
”title”: ”Esimerkkiartikkeli”,
”provider_name”: ”Example”,
”provider_url”: ”https://example.com”,
”html”: ”<blockquote>…</blockquote>”,
”width”: 600,
”height”: 338
}

Todellinen sisältö riippuu siitä, mitä WordPressin oEmbed-järjestelmä pystyy kyseisestä sisällöstä muodostamaan.

Mitä oEmbed voi palauttaa?

oEmbed tukee erilaisia sisältötyyppejä.

Yleisiä ovat:

  • rich
  • video
  • photo
  • link

WordPress-sivustolla rich on erityisen kiinnostava, koska sen avulla voidaan palauttaa HTML-pohjainen esitys.

Oman Providerin käyttökohteet

Oma oEmbed Provider voi olla hyödyllinen esimerkiksi:

  • uutisartikkeleissa
  • tapahtumasivuilla
  • videoalustoilla
  • referenssisisällöissä
  • tuotetiedoissa
  • portfolioissa
  • Headless WordPress -ratkaisuissa

Esimerkiksi yrityksen WordPress-sivusto voisi tarjota yksittäisen referenssin upotettavaksi kumppanin verkkosivulle.

oEmbed ja WordPress-artikkelit

Yksinkertaisimmillaan Provider voi tarjota WordPress-artikkelin upotettavana korttina.

Ulkoinen sivusto voisi käyttää URL-osoitetta:

https://example.com/referenssi/yritys-a

ja saada vastauksena esimerkiksi:

Yritys A:n verkkosivustouudistus
Harrasteblogi
[kuva]
Lyhyt kuvaus…

Tämä on kevyempi integraatio kuin kokonaisen REST API -datan käsittely.

oEmbed ei ole sama kuin REST API

REST API ja oEmbed palvelevat eri käyttötarkoituksia.

REST API sopii, kun ulkoinen sovellus tarvitsee strukturoitua dataa.

oEmbed sopii, kun ulkoinen sovellus haluaa helposti upotettavan esityksen tietystä URL-osoitteesta.

Esimerkiksi:

REST API
→ title
→ content
→ author
→ metadata
→ taxonomy

kun taas:

oEmbed
→ title
→ thumbnail
→ embed HTML
→ provider

oEmbed on siis enemmän esityskerroksen integraatio.

oEmbed ja Gutenberg

WordPressin lohkoeditori hyödyntää embed-toiminnallisuuksia laajasti.

Jos WordPress-sivusto tunnistaa URL-osoitteen oEmbed-sisällöksi, käyttäjä voi saada siitä suoraan embed-lohkon.

Oman Providerin kohdalla tämä mahdollistaa vastaavan kokemuksen myös mukautetulle palvelulle.

URL:n tunnistaminen

Providerin pitää tietää, mitkä URL-osoitteet se hyväksyy.

Esimerkiksi:

wp_oembed_add_provider(
’#https://example\.com/video/.*#i’,
’https://example.com/wp-json/oembed/1.0/embed’,
true
);

Tässä tapauksessa vain tietyn URL-rakenteen mukaiset osoitteet tunnistetaan.

URL-mallista kannattaa tehdä mahdollisimman tarkka.

Miksi liian löysä regex on huono?

Jos Provider hyväksyy käytännössä kaikki URL-osoitteet:

https://example.com/*

se voi aiheuttaa odottamattomia osumia.

Parempi on rajata Provider esimerkiksi:

https://example.com/video/{slug}

tai:

https://example.com/referenssi/{slug}

Tällöin integraation käyttäytyminen pysyy ennakoitavana.

Oman oEmbed-vastauksen rakentaminen

Jos halutaan täysi kontrolli palautettavaan sisältöön, voidaan rakentaa oma endpoint tai oma Provider-logiikka.

Vastauksessa voidaan määrittää esimerkiksi:

version
type
title
author_name
author_url
provider_name
provider_url
cache_age
thumbnail_url
thumbnail_width
thumbnail_height
html
width
height

Kaikkia kenttiä ei tarvitse käyttää.

HTML:n turvallisuus

oEmbed-vastauksessa voidaan palauttaa HTML:ää.

Tämä tekee tietoturvasta tärkeän osan toteutusta.

Älä rakenna HTML:ää suoraan epäluotettavasta käyttäjäsyötteestä.

Esimerkiksi otsikko kannattaa käsitellä tarkoitukseen sopivalla escapingillä:

$title = esc_html( $title );

URL-osoitteet puolestaan:

$url = esc_url( $url );

HTML:n rakentamisessa pitää lisäksi varmistaa, ettei käyttäjä pääse lisäämään mielivaltaista JavaScriptiä tai muuta vaarallista sisältöä.

iframe ja oEmbed

Video- ja rich-embedit voivat käyttää iframea.

Esimerkiksi:

<iframe
src=”https://example.com/embed/123”
title=”Video”
loading=”lazy”>
</iframe>

Tällöin pitää huomioida:

  • responsiivisuus
  • title
  • sandboxing tarvittaessa
  • suorituskyky
  • ulkoiset resurssit
  • Content Security Policy

oEmbed ei poista näitä vaatimuksia.

Responsive oEmbed

Providerin palauttaman HTML:n pitäisi toimia myös mobiililaitteilla.

Hyvä rakenne voi olla:

<div class=”embed-wrapper”>
<iframe
src=”…”
title=”Esimerkkisisältö”
loading=”lazy”>
</iframe>
</div>

CSS:

.embed-wrapper {
width: 100%;
aspect-ratio: 16 / 9;
}
.embed-wrapper iframe {
width: 100%;
height: 100%;
border: 0;
}

Jos sisältö ei ole video, kuvasuhde pitää tietenkin määrittää sisällön mukaan.

Välimuisti

oEmbed-kyselyitä voi tulla paljon, jos suosittu sisältö on upotettuna useille sivustoille.

Siksi välimuistilla on tärkeä rooli.

WordPressillä on oEmbediin liittyviä välimuistimekanismeja, mutta oman Providerin kannattaa myös suunnitella:

  • kuinka usein sisältö muuttuu
  • kuinka pitkään vastausta voidaan cachettaa
  • mitä tapahtuu Providerin ollessa hetkellisesti pois käytöstä

Turha ulkoisten pyyntöjen määrä kannattaa minimoida.

cache_age

oEmbed-standardissa voidaan ilmoittaa, kuinka pitkään vastausta voidaan välimuistittaa.

Tämä voi olla hyödyllinen erityisesti sisällössä, joka ei muutu jatkuvasti.

Esimerkiksi uutisartikkelin upotuksessa thumbnail ja otsikko voivat muuttua, mutta julkaistun referenssin tiedot saattavat pysyä samoina vuosia.

oEmbed ja suorituskyky

oEmbed on parhaimmillaan kevyt integraatio.

Jos Provider joutuu tekemään jokaiseen pyyntöön:

  • useita tietokantakyselyitä
  • ulkoisia API-kutsuja
  • raskasta kuvankäsittelyä
  • monimutkaisia laskelmia

suorituskyky voi kärsiä.

Provider kannattaa suunnitella niin, että yleisin kysely voidaan käsitellä nopeasti.

oEmbed ja yksityiset sisällöt

Kaikkea WordPress-sisältöä ei pidä automaattisesti tarjota oEmbedin kautta.

Erityisesti:

  • luonnokset
  • yksityiset julkaisut
  • sisäiset sisällöt
  • henkilötiedot
  • rajoitetut asiakasprojektit

pitää suojata asianmukaisesti.

Providerin pitää tarkistaa, saako pyydetty sisältö todella olla julkisesti upotettavissa.

oEmbed ja käyttäjän oikeudet

Jos Provider tarjoaa vain julkista sisältöä, tilanne on yksinkertaisempi.

Jos Provider voi palauttaa myös yksityistä tai rajattua sisältöä, autentikointi ja authorization pitää suunnitella erikseen.

Pelkkä URL:n tunteminen ei saa antaa pääsyä yksityiseen sisältöön.

oEmbed ja GDPR

Provider voi välittää ulkopuoliselle sivustolle esimerkiksi:

  • tekijän nimen
  • profiilikuvan
  • artikkelin sisällön
  • thumbnailin
  • muita metadata-arvoja

Ennen Providerin julkaisemista kannattaa määrittää, mitä tietoja oikeasti halutaan jakaa.

Erityisesti käyttäjien henkilökohtaisia tietoja ei pidä sisällyttää vastaukseen vahingossa.

oEmbed vs. JavaScript-widget

oEmbed on usein kevyempi vaihtoehto JavaScript-pohjaiselle widgetille.

Widget voisi toimia näin:

Lataa JavaScript
↓
API-kutsu
↓
Data
↓
DOM-renderöinti

oEmbed voi puolestaan tarjota valmiin upotettavan rakenteen.

Se ei kuitenkaan sovi kaikkiin tilanteisiin. Monimutkaiseen interaktiiviseen sovellukseen REST API tai JavaScript-widget voi olla parempi ratkaisu.

Milloin kannattaa käyttää REST API:a?

REST API on parempi, kun ulkoinen sovellus tarvitsee esimerkiksi:

  • kaikki artikkelin kentät
  • Custom Fields
  • taksonomiat
  • kirjoittajan tiedot
  • relaatiot
  • strukturoitua dataa
  • oman käyttöliittymän

oEmbed on parempi, kun tarkoituksena on:

”Näytä tämä WordPress-sisältö helposti toisella sivustolla.”

Oman Providerin testaaminen

Provider kannattaa testata ainakin:

  • validilla URL:llä
  • virheellisellä URL:llä
  • puuttuvalla sisällöllä
  • poistetulla sisällöllä
  • yksityisellä sisällöllä
  • suurella määrällä samanaikaisia pyyntöjä
  • mobiilinäkymässä

Lisäksi kannattaa testata Provideria useammalla oikealla oEmbed-consumerilla.

Yleisimmät virheet

oEmbed Provider -integraatioissa tehdään helposti seuraavia virheitä:

  • URL-regex on liian löysä
  • yksityinen sisältö vuotaa
  • HTML:ää ei escapeta
  • iframe ei ole responsiivinen
  • Provider tekee liian raskaita kyselyitä
  • välimuistia ei hyödynnetä
  • REST API ja oEmbed sekoitetaan keskenään
  • käyttäjätietoja palautetaan tarpeettomasti

Pieni endpoint voi saada yllättävän suuren liikennemäärän, jos sisältö leviää useille ulkopuolisille sivustoille.

Parhaat käytännöt

WordPress oEmbed Provider -integraatiossa kannattaa:

  • rajaa hyväksyttävät URL-osoitteet tarkasti
  • palauta vain tarvittava data
  • tarkista sisällön näkyvyys
  • escape kaikki dynaaminen HTML
  • suunnittele embed responsiiviseksi
  • käytä välimuistia
  • vältä raskaita kyselyitä
  • suojaa yksityinen sisältö
  • huomioi henkilötiedot
  • testaa Provider eri kuluttajilla
  • käytä REST API:a silloin, kun tarvitset varsinaista strukturoitua dataa

Käytännön arkkitehtuuri

Hyvin suunniteltu WordPress oEmbed Provider voi näyttää esimerkiksi tältä:

Ulkoinen sivusto
↓
WordPress URL
↓
oEmbed endpoint
↓
Sisällön validointi
↓
Oikeuksien tarkistus
↓
Välimuisti / WordPress
↓
oEmbed response
↓
HTML / thumbnail / metadata
↓
Ulkoinen sivusto

Tällainen rakenne pitää Providerin roolin selkeänä.

Yhteenveto

WordPress oEmbed Provider mahdollistaa sen, että oma WordPress-sivusto voi tarjota sisältöään helposti muiden verkkosivustojen ja sovellusten upotettavaksi. Se on hyödyllinen erityisesti videoille, artikkeleille, referensseille, tapahtumille ja muille julkisille sisältöobjekteille.

oEmbed ei ole REST API:n korvaaja. Sen vahvuus on yksinkertaisuus: ulkopuolinen järjestelmä antaa URL-osoitteen ja saa takaisin helposti käytettävän kuvauksen sekä tarvittaessa valmiin HTML-upotuksen.

Hyvä Provider kannattaa rakentaa turvallisuuden ja suorituskyvyn ehdoilla. Tarkasti rajatut URL-osoitteet, julkisen sisällön varmistaminen, HTML:n escaping, responsiivinen embed ja välimuisti muodostavat hyvän perustan tuotantokäyttöön.

🤖 Tämä sisältö on tuotettu tekoälyn avulla. Tarkista tiedot alkuperäisistä lähteistä ennen niiden hyödyntämistä.
Facebook X WhatsApp

Aiheeseen liittyvät artikkelit

8
🍪