Pudotit YouTube-videolinkin editoriin, se toimii. Mutta kun tarvitset sivustollesi kokonaisen soittolistan, joka poimii uudet videot automaattisesti, linkkien manuaalisesta kopioinnista tulee joka kerta työlästä.

PHP-skripti ja YouTube Data API v3 ratkaisevat ongelman kokonaan: se hakee kaikki videot mistä tahansa julkisesta soittolistasta, palauttaa JSONin, ja sinä näytät ne juuri niin kuin haluat, korttiruudukkona, listana, galleriana. Asennukseen menee 15 minuuttia, tarvitset vain API-avaimen ja perus-PHP:n.

Alla on toimiva koodi WordPressille virheenkäsittelyllä, sivutuksella ja välimuistituksella. Lähestymistapa on universaali: se toimii missä tahansa PHP-projektissa, ei vain WP:ssä.

💡 Nopea yleiskatsaus:

• Luo API-avain Google Cloud Consolessa ja linkitä se YouTube Data API v3:een
• Lähetä pyyntö playlistItemsiin ja vastaanota JSON, jossa on kaikki soittolistan videot
• Jäsennä vastaus, kerää pikkukuvat ja linkit, näytä ne ruudukossa sivulla
• Lisää sivutus yli 50 videon soittolistoille ja välimuistitus set_transient()-funktiolla

Vaihe 1: Luo YouTube Data API v3 -avain

API-avain tunnistaa sovelluksesi YouTubelle ja seuraa kiintiöitä. Luodaan ilmaiseksi, päiväraja on 10 000 yksikköä. Yksi avain riittää mainiosti useimmille sivustoille.

Mene Google Cloud Consoleen Google-tililläsi. Luo uusi projekti, projektin valintapainike on yläpalkissa, sitten New Project. Nimeä se kuvaavasti, esimerkiksi my-youtube-feed.

Projektin luomisen jälkeen siirry kohtaan APIs & Services → Library. Kirjoita hakupalkkiin YouTube Data API v3 ja klikkaa Enable. Ilman tätä vaihetta avain ei linkity oikeaan APIin, ja pyynnöt palauttavat 403-virheen.

Nyt itse avain. Avaa sivupalkista Credentials, klikkaa Create Credentials → API key. Järjestelmä luo avaimen ja näyttää sen modaali-ikkunassa. Kopioi se heti: ikkunan sulkemisen jälkeen avain näkyy listassa, mutta sen arvo on osittain piilotettu.

Muista klikata Restrict key. Valitse API restrictions -osiosta YouTube Data API v3, jolloin avain ei toimi muissa API-rajapinnoissa, vaikka se päätyisi julkiseen repositorioon. Paikalliskehityksessä HTTP-referrer-kentän voi jättää tyhjäksi.

Avain näyttää tältä: AIzaSyD-.... Tallenna se wp-config.php-tiedostoon define('YOUTUBE_API_KEY', '...')-rivillä ja lisää wp-config.php .gitignore-tiedostoon. Älä kovakoodaa avainta teemakoodiin.

Vaihe 2: Hae videot soittolistalta

Pyyntöön tarvitset kaksi asiaa: API-avaimen ja soittolistan ID:n. ID poimitaan URL-osoitteesta: avaa soittolista YouTubessa, kopioi osoiteriviltä. URL:n list=-parametri on soittolistan ID: esimerkiksi PLp0YhAQYkolGq1e6r1m5....

Perus-PHP-pyyntö playlistItems-päätepisteeseen:

1
$api_key     = 'AIzaSy...';          // your key from step 1
2
$playlist_id = 'PLp0YhAQYkolG...';   // playlist ID from URL
3
 
4
$api_url = 'https://www.googleapis.com/youtube/v3/playlistItems' .
5
    '?part=snippet' .
6
    '&maxResults=50' .
7
    '&playlistId=' . urlencode($playlist_id) .
8
    '&key=' . $api_key;
9
 
10
$response = file_get_contents($api_url);
11
$data     = json_decode($response, true);
12
 
13
if (json_last_error() !== JSON_ERROR_NONE) {
14
    die('JSON parsing error: ' . json_last_error_msg());
15
}

Mitä tässä tapahtuu. part=snippet pyytää perustiedot: otsikon, kuvauksen, pikkukuvan, sijainnin soittolistalla. Täydellistä sarjaa varten voit määrittää snippet,contentDetails,status. maxResults=50 on maksimi per pyyntö, API palauttaa oletuksena 5 tietuetta, joten parametri kannattaa määrittää eksplisiittisesti. Koodaa playlistId urlencode()-funktiolla erikoismerkkien varalta.

Tuotantokäyttöä varten korvaa file_get_contents() wp_remote_get()-funktiolla (WordPressissä) tai cURL:lla, jossa on aikakatkaisu. Suora kutsu epäonnistuu, jos Google on tilapäisesti pois käytöstä tai verkko on hidas. Tässä versio HTTP-virheenkäsittelyllä:

1
$response = wp_remote_get($api_url, [
2
    'timeout' => 15,
3
    'headers' => ['Accept' => 'application/json'],
4
]);
5
 
6
if (is_wp_error($response)) {
7
    error_log('YouTube API error: ' . $response->get_error_message());
8
    return [];
9
}
10
 
11
$http_code = wp_remote_retrieve_response_code($response);
12
if ($http_code !== 200) {
13
    error_log('YouTube API HTTP ' . $http_code);
14
    return [];
15
}
16
 
17
$body = wp_remote_retrieve_body($response);
18
$data = json_decode($body, true);

Kaksi tarkistustasoa: ensin is_wp_error() havaitsee verkkovirheet, sitten varmistamme HTTP-koodin. Jos jokin menee pieleen, palautamme tyhjän taulukon, sivusto ei kaadu.

Vaihe 3: Näytä videolista sivulla

API palauttaa items-taulukon. Jokainen elementti on yksi soittolistan video. Vastauksen rakenne:

1
{
2
  "items": [
3
    {
4
      "snippet": {
5
        "title": "Video title",
6
        "description": "Description...",
7
        "thumbnails": {
8
          "default":  { "url": "https://i.ytimg.com/.../default.jpg" },
9
          "medium":   { "url": "https://i.ytimg.com/.../mqdefault.jpg" },
10
          "high":     { "url": "https://i.ytimg.com/.../hqdefault.jpg" }
11
        },
12
        "resourceId": {
13
          "videoId": "dQw4w9WgXcQ"
14
        }
15
      }
16
    }
17
  ]
18
}

Video tunnistetaan resourceId.videoId-kentällä. Siitä kootaan linkki https://www.youtube.com/watch?v=<videoId>. Pikkukuvat ovat thumbnails-kentässä kolmessa resoluutiossa: korttiruudukkoon ota medium, kompaktiin listaan default.

Tulostuskoodi WordPressille, shortcode tai sivupohja:

1
if (! empty($data['items'])) {
2
    echo '<div class="yt-playlist-grid">';
3
 
4
    foreach ($data['items'] as $item) {
5
        $title     = esc_html($item['snippet']['title']);
6
        $video_id  = esc_attr($item['snippet']['resourceId']['videoId']);
7
        $thumbnail = esc_url($item['snippet']['thumbnails']['medium']['url']);
8
        $link      = 'https://www.youtube.com/watch?v=' . $video_id;
9
 
10
        printf(
11
            '<a href="%s" class="yt-card" target="_blank" rel="noopener">'
12
            . '<img src="%s" alt="%s" loading="lazy">'
13
            . '<span>%s</span></a>',
14
            $link, $thumbnail, $title, $title
15
        );
16
    }
17
 
18
    echo '</div>';
19
}

Kolme asiaa, jotka säästävät debuggaamiseen kuluvaa aikaa:

• loading="lazy". Kun sivulla on 50 videota ilman lazy loadingia, PageSpeed romahtaa. Attribuutti kertoo selaimelle: lataa kuva vasta, kun siihen on vieritetty.
• esc_html()** ja esc_url().** Pakollinen sanitointi WordPressille. Videoiden otsikot sisältävät joskus lainausmerkkejä ja HTML-entiteettejä, ilman escaperausta ne rikkovat asettelun.
• target="_blank"** ja rel="noopener".** Avaa YouTube uudessa välilehdessä, mutta älä anna sille pääsyä window.opener-objektiin, suoja tab-nappingia vastaan.

CSS ruudukolle, minimaalinen, vakio-teemalle:

1
.yt-playlist-grid {
2
    display: grid;
3
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
4
    gap: 20px;
5
}
6
.yt-card {
7
    text-decoration: none;
8
    color: inherit;
9
    border-radius: 8px;
10
    overflow: hidden;
11
    transition: transform 0.2s;
12
}
13
.yt-card:hover {
14
    transform: translateY(-2px);
15
}
16
.yt-card img {
17
    width: 100%;
18
    aspect-ratio: 16 / 9;
19
    object-fit: cover;
20
}
21
.yt-card span {
22
    display: block;
23
    padding: 10px;
24
    font-weight: 600;
25
    font-size: 14px;
26
}

Ruudukko mukautuu automaattisesti näytön leveyteen: auto-fill + minmax(280px, 1fr) antavat yhdestä useampaan sarakkeeseen ilman media queryitä.

Vaihe 4: Sivutus, kiintiöt ja yleiset virheet

Sivutus. Yksi pyyntö palauttaa enintään 50 videota. Jos soittolistalla on enemmän, vastaukseen ilmestyy nextPageToken-kenttä. Välitä se seuraavassa pyynnössä, API palauttaa seuraavan sivun. Silmukka:

1
$all_items  = [];
2
$page_token = null;
3
 
4
do {
5
    $url = $api_url . '&pageToken=' . urlencode($page_token ?? '');
6
    // ... API request ...
7
    $all_items  = array_merge($all_items, $data['items'] ?? []);
8
    $page_token = $data['nextPageToken'] ?? null;
9
} while ($page_token && count($all_items) < 500);

Silmukka katkeaa 500 videon kohdalla, mikä on järkevä yläraja sivuston sivulle. Ilman rajaa riskinä on koko kiintiön kuluminen muutamalla latauksella.

Kiintiöt. Jokainen playlistItems.list-kutsu maksaa 1 kiintiöyksikön, tämän vahvistaa Googlen virallinen kiintiötaulukko. Päiväraja on 10 000 yksikköä. Se tarkoittaa 10 000 pyyntöä päivässä, enemmän kuin tarpeeksi valtaosalle sivustoista. Mutta jos soittolista päivittyy usein, lisää välimuistitus:

1
$cache_key   = 'yt_playlist_' . md5($playlist_id);
2
$cached_data = get_transient($cache_key);
3
 
4
if ($cached_data !== false) {
5
    return $cached_data;
6
}
7
 
8
// ... API request ...
9
 
10
set_transient($cache_key, $data, HOUR_IN_SECONDS * 6);

Kuusi tuntia on järkevä tasapaino tuoreuden ja kiintiön säästämisen välillä. Ei-kriittisille soittolistoille aseta 12-24 tuntia. get_transient() ja set_transient() ovat natiiveja WordPress-funktioita, ne toimivat objektivälimuistin (Redis/Memcached) kanssa, jos sellainen on konfiguroitu, muuten ne kirjoittavat wp_options-tauluun.

Yleiset virheet ja mitä niille tehdä:

• 403 Forbidden. APIa ei ole otettu käyttöön projektille Google Cloud Consolessa. Palaa vaiheeseen 1: YouTube Data API v3:n Enable-painiketta on täytynyt klikata. Tarkista myös, onko avaimen asetuksissa IP-rajoitus.
• 400 Bad Request, "API key not valid". Avain on juuri luotu eikä ole vielä aktivoitunut. Odota 2-5 minuuttia: API-rajoitukset eivät astu voimaan välittömästi.
• 404 Not Found. Virheellinen soittolistan ID tai soittolista on yksityinen. API-avain palauttaa vain julkiset ja listaamattomat soittolistat. Yksityiset vaativat OAuth-valtuutuksen.
• Tyhjä items-taulukko kelvollisella ID:llä. Todennäköisimmin soittolista on tyhjä. Avaa soittolistan URL selaimessa ja varmista, että siellä on videoita.

💻 Video: YouTube Data API v3 käytännössä

Lyhyt video aiheesta, näyttää visuaalisesti koko prosessin avaimen luomisesta videolistan näyttämiseen:

⁉️🤔 Usein kysytyt kysymykset

Toimiiko API yksityisten soittolistojen kanssa?

Ei. playlistItems.list API-avaimella palauttaa vain julkiset ja listaamattomat soittolistat. Yksityisiin tarvitset OAuth-valtuutuksen: käyttäjän on eksplisiittisesti annettava sovelluksellesi pääsy tililleen. Julkiselle aggregaattisivustolle API-avain riittää.

Voinko hakea videoita jonkun toisen soittolistalta?

Kyllä, jos soittolista on julkinen. API-avain ei ole sidottu soittolistan omistajaan, se tunnistaa sovelluksesi, ei YouTube-käyttäjää. Mikä tahansa julkinen soittolista on käytettävissä ID:n perusteella riippumatta siitä, kuka sen loi.

Miten saan yli 50 videota kerralla?

Et mitenkään, se on maxResults-parametrin kova raja playlistItems-päätepisteelle, vahvistettu Googlen dokumentaatiossa. Käytä sivutusta nextPageToken-tokenin avulla (vaihe 4). 300 videon soittolistaan tarvitset 6 peräkkäistä pyyntöä, ne kuluttavat yhteensä 6 kiintiöyksikköä 10 000 päivittäisestä.

Miksi videoiden pikkukuvat eivät näy?

Tarkista URL thumbnails-kentässä: kentän nimi on url, ei link eikä src. Toinen syy: mainosestäjät blokkaavat joskus i.ytimg.com-domainin. Kolmas: jotkin vanhat videot (ennen vuotta 2010) eivät sisällä korkean resoluution pikkukuvia, ota default, se on aina olemassa.

Mitä tehdä, jos avain vaarantuu?

Mene välittömästi Google Cloud Consoleen → Credentials, etsi avain ja klikkaa Delete. Luo uusi. Vanha avain deaktivoituu 5 minuutin kuluessa. Säilytä avain define('YOUTUBE_API_KEY', '...')-rivillä wp-config.php-tiedostossa ja sulje tämä tiedosto repositorion ulkopuolelle .gitignore-tiedostolla.

Kannattaako API:n kanssa nähdä vaivaa, jos soittolistalinkin voi vain liittää?

Jos yksi staattinen soittolista iframen kautta riittää sivustolle, et tarvitse APIa, YouTube tarjoaa valmiin upotuskoodin. Mutta heti kun tarvitset uusien videoiden automaattista poimintaa, päivämäärän mukaan suodattamista, asettelun mukauttamista tai pikkukuvien näyttämistä epästandardissa designissa, API on ainoa toimiva vaihtoehto.

WordPress-sivustolle wp_remote_get() + set_transient() -yhdistelmä poistaa kiintiö- ja nopeushuolet kokonaan: muutaman tunnin välein skripti hakee JSONin, välimuistittaa sen, ja frontend toimii välimuistin kanssa välittömästi. Soittolista päivittyy itsestään, editorin ei tarvitse klikata mitään.

Jos teemasi tukee mukautettua PHP:tä pohjissa, ota koodi vaiheesta 3, muuta CSS vastaamaan designiasi. Jos käytät page builderia, kääri PHP-logiikka shortcodeen ja lisää se minne tahansa muodossa [youtube_playlist id="PLp0..."].

Kokeile yhdellä soittolistalla: 15 minuuttia avaimeen ja ensimmäiseen pyyntöön, niin näet, toimiiko lähestymistapa sinun tarpeeseesi. Ja jos olet jo käyttänyt APIa muihin tarkoituksiin, kirjoita kommentteihin, mikä päätepiste osoittautui hyödyllisimmäksi.