TMDB API Anahtarı Nasıl Alınır ve Film Veritabanı API'si Sorgulama

The Movie Database (TMDB), filmler, TV şovları, oyuncu kadrosu ve sanat eserlerinin topluluk tarafından oluşturulmuş bir kataloğudur. API'si ticari olmayan kullanım için ücretsizdir, yeter ki TMDB'ye atıfta bulunun; bu da onu ücretsiz film API'leri listesindeki olağan başlangıç noktası haline getirir. İşin püf noktası katılım sürecidir: TMDB size iki farklı kimlik bilgisi verir ve resmi başlangıç kılavuzu hangisini kullanacağınızı zaten bildiğinizi varsayar.

Bu kılavuz, tüm yolu kapsar: hesap, anahtar isteği, v3 anahtarı ile v4 okuma erişim belirteci arasındaki fark, curl ve Python'da ilk arama ve detay çağrıları, aynı çağrıların Apidog'da test olarak kaydedilmesi ve ilk gün karşılaşacağınız oran limitleri, atıf kuralları ve hatalar.

Başlamadan önce ihtiyacınız olanlar

• Doğrulanmış e-posta adresine sahip bir TMDB hesabı. API, doğrulanmamış hesapları 401 hatasıyla reddeder.
• Bir masaüstü tarayıcısı. TMDB'nin belgeleri, API kayıt sayfalarının mobil cihazlar için optimize edilmediğini belirtiyor.
• curl veya requests paketiyle Python 3.
• Token'ı güvenli bir şekilde saklamak ve istekleri tutmak için Apidog. macOS, Windows veya Linux için Apidog'u indirin.

Adım 1: bir TMDB hesabı oluşturun

themoviedb.org adresine gidin, "TMDB'ye Katıl" düğmesine tıklayın ve bir e-posta adresiyle kaydolun. API ayarlarına dokunmadan önce doğrulama e-postasını açın ve onaylayın. Bunu atlarsanız, daha sonra kafa karıştırıcı bir 401 hatasıyla karşılaşırsınız, durum kodu 32: "E-posta doğrulanmadı: E-posta adresiniz doğrulanmadı."

Adım 2: API anahtarını isteyin

Giriş yaptıktan sonra, hesap ayarlarınızı açın ve sol kenar çubuğundaki "API"ye tıklayın. TMDB'nin SSS bölümü bunu tek rota olarak açıklar: "API anahtarı için hesap ayarları sayfanızdaki sol kenar çubuğundan 'API' bağlantısına tıklayarak başvurabilirsiniz."

API kullanım koşullarını kabul edecek, ardından kısa bir başvuru formu dolduracaksınız: ne geliştirdiğiniz, varsa bir URL, verileri nasıl kullanacağınıza dair bir özet ve kullanım türü. Kişisel projeler, prototipler ve dahili araçlar için geliştirici seçeneğini seçin. TMDB, bir projeyi "ana amacı sahibine gelir sağlamaksa" ticari olarak kabul eder ve bu yol, satış ekibiyle yazılı bir anlaşma gerektirir.

Gönderdikten sonra, aynı ayarlar sayfası iki kimlik bilgisi gösterir:

• API Anahtarı, v3 kimlik doğrulaması için etiketlenmiştir. 32 karakterlik bir onaltılık dize.
• API Okuma Erişim Belirteci, çok daha uzun bir JWT tarzı dize.

TMDB bir inceleme zaman çizelgesi yayınlamaz; pratikte her iki değer de form gönderilir gönderilmez görünür. Bunları diğer tüm sırlar gibi ele alın ve commit'lerden, sohbet pencerelerinden ve ekran görüntülerinden uzak tutun.

v3 API anahtarı ile v4 okuma erişim belirteci karşılaştırması

İki kimlik bilgisi "eski" ve "yeni" değildir. Aynı uygulamayı tanımlamanın iki yoludur ve resmi kimlik doğrulama belgeleri her ikisinin de "aynı düzeyde erişim sağladığını" belirtir.

TMDB'nin kendi önerisi Taşıyıcı belirteçtir: "Kimlik doğrulaması için varsayılan yöntem erişim belirtecinizi kullanmaktır" ve "hem v3 hem de v4 yöntemlerinde kullanabileceğiniz tek bir kimlik doğrulama sürecinin ek faydasına sahiptir."

İstemciniz başlıkları ayarlayamıyorsa Taşıyıcı başlığını kullanın. Kimlik bilgisini URL'den uzak tutmak, herhangi bir API anahtarı ile taşıyıcı belirteç kararının arkasındaki aynı argümandır: URL'ler günlüğe kaydedilir, önbelleğe alınır ve paylaşılır.

Bir ayrım daha. Bu makaledeki her şey, yalnızca uygulama kimlik bilgisini gerektiren salt okunur katalog verileridir. v4 API, listeler, favoriler, derecelendirmeler ve izleme listeleri gibi hesap özelliklerini ekler. Bunlara bir TMDB kullanıcısı için yazmak ekstra bir el sıkışması gerektirir: /4/auth/request_token adresinden bir istek belirteci, kullanıcı onayı, ardından /4/auth/access_token adresinden bir kullanıcı erişim belirteci. Bunların hiçbiri film aramak veya detayları okumak için gerekli değildir.

Adım 3: ilk isteğinizi yapın

Tüm v3 çağrıları https://api.themoviedb.org/3 adresine gider. İki uç nokta çoğu ilk projeyi kapsar: başlığa göre arama, ardından kimliğe göre detayları getir.

curl ile bir film arayın

curl --request GET \
  --url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
  --header 'Authorization: Bearer YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

Yanıt, page, results, total_pages ve total_results içeren bir sayfa nesnesidir. Her sonuç id, title, release_date, overview, poster_path, genre_ids ve vote_average içerir. TMDB'nin kendi arama örneğinde, "dövüş kulübü" için ilk isabet kimliği 550, yayınlanma tarihi 1999-10-15'tir.

v3 anahtarıyla aynı çağrı şöyle görünür. Hiçbir kimlik doğrulama başlığı olmadığını unutmayın:

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

Python ile film detaylarını alın

Şimdi aramadan kimliği alın ve tam kaydı isteyin. Film detayları uç noktası runtime, genres, budget, revenue ve overview döndürür. append_to_response parametresi, aynı gidiş-dönüşte krediler gibi alt kaynakları, istek başına 20'ye kadar ekler.

import os
import requests

TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}


def search_movie(title):
    r = requests.get(
        f"{BASE}/search/movie",
        params={"query": title, "include_adult": "false", "language": "en-US"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]


def movie_details(movie_id):
    r = requests.get(
        f"{BASE}/movie/{movie_id}",
        params={"append_to_response": "credits"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])

Son satır, insanların gözden kaçırdığı kısımdır. poster_path yalnızca bir yoldur. Görsel temelleri kılavuzunun açıkladığı gibi, çalışan bir URL https://image.tmdb.org/t/p/, ardından w500 veya original gibi bir boyut, sonra da yoldur. /3/configuration her geçerli boyutu listeler.

Adım 4: istekleri Apidog'da çalıştırın ve kaydedin

Ham çağrılar çalıştıktan sonra, onları kaybetmeyeceğiniz bir yere taşıyın. Apidog'da bu birkaç dakika sürer ve size kaydedilmiş, paylaşılabilir bir test bırakır.

1. Bir proje oluşturun ve "TMDB" adında, base_url değeri https://api.themoviedb.org/3 ve tmdb_token değerinde okuma erişim belirtecinizi tutan iki değişkenli bir ortam ekleyin. Belirteci bir sır olarak işaretleyin, böylece kullanıcı arayüzünde maskelenir ve dışa aktarmalardan uzak tutulur; ortam ve gizli değişkenler kılavuzu seçenekleri kapsar.
2. {{base_url}}/search/movie adresine query parametresiyle bir GET isteği ekleyin. Kimlik Doğrulama sekmesinde Taşıyıcı Belirteç'i seçin ve {{tmdb_token}} girin. Gönderin ve 200 yanıtı ile bir results dizisi aldığınızı onaylayın.
3. {{base_url}}/movie/{{movie_id}} adresine ikinci bir GET isteği ekleyin. İlk isteğin işlem sonrası bölümünde, results[0].id değerini movie_id içine çıkarın, böylece ikinci çağrı her zaman ilkini takip eder.
4. Her ikisini de onaylarla birlikte bir test senaryosu olarak kaydedin: durum 200'e eşit, total_results 0'dan büyük ve detay yanıtındaki title boş değil. Entegrasyon değiştiğinde çalıştırın.

Bu verilerle bir ön uç mu geliştiriyorsunuz? Arama uç noktası için sahte sunucuyu açın. Apidog, şemaya uygun bir yanıt üretir, böylece UI ekibi, canlı bir belirteç veya TMDB'nin limitlerine karşı gerçek istekler olmadan poster ızgarasını oluşturabilir.

Oran limitleri ve atıf kuralları

Aşağıdaki her şey TMDB'nin belgelerinden alıntıdır.

Oran limitleri. TMDB'nin oran sınırlama sayfası, her 10 saniyede bir 40 isteklik orijinal limitin 16 Aralık 2019'da devre dışı bırakıldığını belirtiyor. Üst sınırlar "gereksiz yere yüksek toplu kazımayı azaltmaya yardımcı olmak için" kalır ve "saniyede 40 istek aralığında bir yerdedir." Bu rakam haber verilmeksizin değişebilir, bu nedenle herhangi bir HTTP 429'a saygı gösterin, geri çekilin ve tekrar deneyin.

Maliyet. SSS'den: "API'mız, TMDB'yi verilerin ve/veya görsellerin kaynağı olarak belirttiğiniz sürece ticari olmayan amaçlar için ücretsizdir." Ticari projeler sales@themoviedb.org ile iletişime geçmelidir.

Atıf. Uygulamanızda TMDB logosunu ve bu bildirimi gösterin: "Bu ürün TMDB API'sini kullanır ancak TMDB tarafından onaylanmamış veya belgelendirilmemiştir." API kullanım koşulları biraz daha uzun bir ifade kullanır ve logonun kendi markanızdan daha az belirgin olmasını ve asla yeniden renklendirilmemesini, gerilmemesini, ters çevrilmemesini veya döndürülmemesini gerektirir.

Önbelleğe alma. Koşullar, TMDB verilerini altı aydan daha uzun süre önbelleğe almayı yasaklar. İhtiyacınız olanı saklayın, ancak bir yenileme planlayın.

SLA Yok. TMDB bunu açıkça belirtir. Zaman aşımları ve yeniden denemeler oluşturun.

Anahtar hijyeni. Her iki kimlik bilgisi de ortam değişkenlerinde veya bir sır yöneticisinde bulunmalıdır, asla kaynak kodunda değil. Bir tanesi bir depoya düşerse, ayarlar sayfasından döndürün ve geçmişinizde bir API anahtarı sızıntı kontrolü çalıştırın.

Yaygın hatalar ve anlamları

TMDB, HTTP durumuyla birlikte status_code ve status_message içeren bir JSON gövdesi döndürür. Hata referansı düzinelerce kodu listeler; bunlar ilk karşılaşacağınız hatalardır.

SSS

TMDB API anahtarı ücretsiz mi?

Evet, atıfta bulunarak ticari olmayan kullanım için. Ücretli self-servis katman yok. Projeniz gelir sağlıyorsa, TMDB satış ekibi aracılığıyla ticari bir anlaşma yapmanızı ister.

API anahtarını mı yoksa okuma erişim belirtecini mi kullanmalıyım?

Okuma erişim belirtecini bir Taşıyıcı başlığı olarak kullanın. TMDB bunu varsayılan olarak adlandırır, hem v3 hem de v4'te çalışır ve URL'lerinizden uzak kalır. v3 anahtarı, yalnızca sorgu parametreleri gönderebilen araçlar için mevcuttur. Konsept yeniyse, API anahtarı nedir üzerine bu giriş, TMDB'nin izlediği modeli açıklar.

TMDB'yi doğrudan bir tarayıcıdan veya mobil uygulamadan çağırabilir miyim?

Yapabilirsiniz, ancak istemciye gönderilen her şey, belirteciniz de dahil olmak üzere herkese açıktır. Kişisel bir proje için bu kabul edilebilir bir risktir. Kullanıcıları olan herhangi bir şey için, TMDB'nin önüne küçük bir arka uç veya sunucusuz işlev koyun, belirteci orada saklayın ve popüler sorguları önbelleğe alın.

v3 ve v4 arasındaki fark nedir?

v3 katalogdur: arama, film ve TV detayları, kişiler, görseller, keşif. v4, listeler, favoriler, derecelendirmeler ve izleme listeleri gibi hesap özelliklerini kapsar ve yazma uç noktaları bir kullanıcı erişim belirteci gerektirir. Okuma erişim belirteciniz her ikisinde de kimlik doğrulaması yapar.

Buradan sonra nereye gitmeli?

Artık çalışan bir TMDB API anahtarınız, hangi kimlik bilgisini göndereceğinize dair bir kuralınız, curl ve Python'da arama-detay akışınız ve aynı akışın bir Apidog test senaryosu olarak kaydedilmiş hali var. Sonra, filtrelenmiş göz atma için discover/movie ekleyin ve paylaşmadan önce uygulamanıza atıf bildirimini koyun. Katalogdaki diğer her şey aynı temel URL'yi, Taşıyıcı başlığını ve hata biçimlerini kullanır.