วิธีขอ TMDB API Key และดึงข้อมูลจาก TMDB API

The Movie Database (TMDB) (ฐานข้อมูลภาพยนตร์) คือแคตตาล็อกภาพยนตร์ รายการทีวี นักแสดง และอาร์ตเวิร์คที่สร้างขึ้นโดยชุมชน API ของ TMDB ให้ใช้งานได้ฟรีสำหรับการใช้งานที่ไม่ใช่เชิงพาณิชย์ ตราบใดที่คุณให้เครดิตแก่ TMDB ซึ่งทำให้เป็นจุดเริ่มต้นตามปกติในรายการ API ภาพยนตร์ฟรี ข้อเสียคือการเริ่มต้นใช้งาน: TMDB มอบข้อมูลประจำตัวให้คุณสองชุด และ คู่มือเริ่มต้นใช้งาน อย่างเป็นทางการถือว่าคุณรู้อยู่แล้วว่าจะใช้ชุดใด

คู่มือนี้ครอบคลุมเส้นทางทั้งหมด: บัญชี, การร้องขอคีย์, คีย์ v3 เทียบกับโทเค็นการเข้าถึงแบบอ่าน v4, การเรียกค้นหาและรายละเอียดครั้งแรกใน curl และ Python, การเรียกเดียวกันที่บันทึกเป็นชุดทดสอบใน Apidog, และขีดจำกัดอัตรา, กฎการอ้างอิง, และข้อผิดพลาดที่คุณจะพบในวันแรก

สิ่งที่คุณต้องมีก่อนเริ่มต้น

• บัญชี TMDB พร้อมที่อยู่อีเมลที่ยืนยันแล้ว API จะปฏิเสธบัญชีที่ยังไม่ได้ยืนยันด้วยรหัส 401
• เบราว์เซอร์เดสก์ท็อป เอกสารของ TMDB ระบุว่าหน้าการลงทะเบียน API ไม่ได้ปรับให้เหมาะกับอุปกรณ์มือถือ
• curl หรือ Python 3 พร้อมแพ็คเกจ requests
• Apidog เพื่อจัดเก็บโทเค็นอย่างปลอดภัยและเก็บคำขอ ดาวน์โหลด Apidog สำหรับ macOS, Windows หรือ Linux

ขั้นตอนที่ 1: สร้างบัญชี TMDB

ไปที่ themoviedb.org คลิก “เข้าร่วม TMDB” และลงทะเบียนด้วยที่อยู่อีเมล เปิดอีเมลยืนยันและยืนยันก่อนที่จะแตะการตั้งค่า API หากข้ามขั้นตอนนี้ไป คุณจะพบกับข้อผิดพลาด 401 ที่ชวนสับสนในภายหลัง ซึ่งมีรหัสสถานะ 32: “อีเมลยังไม่ได้ยืนยัน: ที่อยู่อีเมลของคุณยังไม่ได้รับการยืนยัน”

ขั้นตอนที่ 2: ร้องขอคีย์ API

เมื่อคุณเข้าสู่ระบบแล้ว ให้เปิดการตั้งค่าบัญชีของคุณและคลิก “API” ในแถบด้านข้างซ้าย คำถามที่พบบ่อย (FAQ) ของ TMDB อธิบายว่านี่เป็นเส้นทางเดียว: “คุณสามารถสมัครคีย์ API ได้โดยคลิกที่ลิงก์ ‘API’ จากแถบด้านข้างซ้ายภายในหน้าการตั้งค่าบัญชีของคุณ”

คุณจะต้องยอมรับข้อกำหนดการใช้งาน API จากนั้นกรอกใบสมัครสั้นๆ: คุณกำลังสร้างอะไร, URL หากคุณมี, สรุปวิธีการใช้ข้อมูล, และประเภทการใช้งาน เลือกตัวเลือกนักพัฒนาสำหรับโปรเจกต์ส่วนตัว, โปรโตไทป์, และเครื่องมือภายใน TMDB นับโปรเจกต์ว่าเป็นเชิงพาณิชย์ “หากวัตถุประสงค์หลักคือการสร้างรายได้เพื่อประโยชน์ของเจ้าของ” และเส้นทางนั้นต้องการข้อตกลงเป็นลายลักษณ์อักษรกับทีมขายของพวกเขา

หลังจากคุณส่งแล้ว หน้าการตั้งค่าเดียวกันจะแสดงข้อมูลรับรองสองชุด:

• คีย์ API ระบุสำหรับการรับรองความถูกต้อง v3 เป็นสตริงเลขฐานสิบหก 32 ตัวอักษร
• โทเค็นการเข้าถึงแบบอ่าน API ซึ่งเป็นสตริงแบบ JWT ที่ยาวกว่ามาก

TMDB ไม่ได้เผยแพร่ไทม์ไลน์การตรวจสอบ ในทางปฏิบัติ ค่าทั้งสองจะปรากฏขึ้นทันทีที่ฟอร์มถูกส่งไป ปฏิบัติต่อสิ่งเหล่านี้เหมือนกับความลับอื่น ๆ และเก็บไว้ให้ห่างจาก commit, หน้าต่างแชท และภาพหน้าจอ

คีย์ API v3 เทียบกับโทเค็นการเข้าถึงแบบอ่าน v4

ข้อมูลรับรองทั้งสองไม่ใช่ “เก่า” และ “ใหม่” แต่เป็นสองวิธีในการระบุแอปพลิเคชันเดียวกัน และ เอกสารการรับรองความถูกต้อง อย่างเป็นทางการระบุว่าทั้งสอง “ให้ระดับการเข้าถึงที่เหมือนกัน”

คำแนะนำของ TMDB คือโทเค็น Bearer: “วิธีการรับรองความถูกต้องเริ่มต้นคือการใช้โทเค็นการเข้าถึงของคุณ” และมี “ประโยชน์เพิ่มเติมคือเป็นกระบวนการรับรองความถูกต้องแบบเดี่ยวที่คุณสามารถใช้ได้ทั้งวิธี v3 และ v4”

ใช้ส่วนหัว Bearer เว้นแต่ไคลเอนต์ของคุณไม่สามารถตั้งค่าส่วนหัวได้ การเก็บข้อมูลรับรองออกจาก URL เป็นเหตุผลเดียวกับการตัดสินใจ คีย์ API เทียบกับโทเค็น Bearer: URL จะถูกบันทึก, แคช และแชร์

ข้อแตกต่างอีกประการหนึ่ง ทุกอย่างในบทความนี้เป็นข้อมูลแคตตาล็อกแบบอ่านอย่างเดียว ซึ่งต้องการเพียงข้อมูลรับรองแอปพลิเคชันเท่านั้น API v4 เพิ่มคุณสมบัติบัญชี เช่น รายการ, รายการโปรด, การให้คะแนน และรายการที่ต้องการดู การเขียนข้อมูลเหล่านั้นสำหรับผู้ใช้ TMDB ต้องมีการจับมือกันเพิ่มเติม: โทเค็นคำขอจาก /4/auth/request_token, การอนุมัติของผู้ใช้, จากนั้นโทเค็นการเข้าถึงของผู้ใช้จาก /4/auth/access_token ไม่มีสิ่งใดจำเป็นสำหรับการค้นหาภาพยนตร์หรืออ่านรายละเอียด

ขั้นตอนที่ 3: ส่งคำขอแรกของคุณ

การเรียก v3 ทั้งหมดส่งไปที่ https://api.themoviedb.org/3 ปลายทางสองจุดครอบคลุมโปรเจกต์แรกส่วนใหญ่: ค้นหาด้วยชื่อ แล้วดึงรายละเอียดด้วย id

ค้นหาภาพยนตร์ด้วย curl

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'

การตอบกลับคือออบเจกต์หน้าที่มี page, results, total_pages และ total_results แต่ละผลลัพธ์มี id, title, release_date, overview, poster_path, genre_ids และ vote_average ใน ตัวอย่างการค้นหา ของ TMDB การค้นหาครั้งแรกสำหรับ “fight club” คือ id 550, ออกฉาย 1999-10-15

การเรียกเดียวกันกับคีย์ v3 จะมีลักษณะดังนี้ โปรดทราบว่าไม่มีส่วนหัวการรับรองความถูกต้องเลย:

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

รับรายละเอียดภาพยนตร์ด้วย Python

ตอนนี้ให้นำ id จากการค้นหาและขอระเบียนฉบับเต็ม ปลายทางรายละเอียดภาพยนตร์ ส่งคืน runtime, genres, budget, revenue และ overview พารามิเตอร์ append_to_response จะเพิ่มทรัพยากรย่อย เช่น เครดิต ไปยังรอบการเดินทางเดียวกัน สูงสุด 20 รายการต่อคำขอ

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"])

บรรทัดสุดท้ายคือส่วนที่ผู้คนมักจะพลาด poster_path เป็นเพียงเส้นทางเท่านั้น ดังที่ คู่มือพื้นฐานรูปภาพ อธิบายไว้ URL ที่ใช้งานได้คือ https://image.tmdb.org/t/p/ จากนั้นเป็นขนาด เช่น w500 หรือ original จากนั้นเป็นเส้นทาง /3/configuration แสดงรายการขนาดที่ถูกต้องทั้งหมด

ขั้นตอนที่ 4: รันและบันทึกคำขอใน Apidog

เมื่อการเรียกดิบทำงานได้แล้ว ให้ย้ายไปไว้ในที่ที่คุณจะไม่ทำหาย ใน Apidog ขั้นตอนนี้ใช้เวลาไม่กี่นาทีและทำให้คุณมีชุดทดสอบที่บันทึกและแชร์ได้

1. สร้างโปรเจกต์และเพิ่มสภาพแวดล้อมที่ชื่อ “TMDB” พร้อมตัวแปรสองตัว: base_url ตั้งค่าเป็น https://api.themoviedb.org/3 และ tmdb_token เก็บโทเค็นการเข้าถึงแบบอ่านของคุณ ทำเครื่องหมายโทเค็นว่าเป็นความลับเพื่อให้ถูกปกปิดใน UI และเก็บออกจากไฟล์ส่งออก คู่มือตัวแปรสภาพแวดล้อมและความลับ ครอบคลุมตัวเลือกต่างๆ
2. เพิ่มคำขอ GET ไปยัง {{base_url}}/search/movie พร้อมพารามิเตอร์ query บนแท็บ Auth ให้เลือก Bearer Token และป้อน {{tmdb_token}} ส่งแล้วยืนยันว่าคุณได้รับ 200 และอาร์เรย์ results
3. เพิ่มคำขอ GET ตัวที่สองไปยัง {{base_url}}/movie/{{movie_id}} ในตัวประมวลผลหลังของคำขอแรก ให้แยก results[0].id ไปยัง movie_id เพื่อให้การเรียกครั้งที่สองติดตามการเรียกครั้งแรกเสมอ
4. บันทึกทั้งสองเป็นสถานการณ์ทดสอบพร้อมการยืนยัน: สถานะเท่ากับ 200, total_results มากกว่า 0 และ title ในการตอบกลับรายละเอียดไม่ว่างเปล่า รันเมื่อใดก็ตามที่การรวมระบบเปลี่ยนแปลง

กำลังสร้างส่วนหน้าสำหรับข้อมูลนี้อยู่ใช่ไหม? เปิดใช้งาน mock server สำหรับปลายทางการค้นหา Apidog สร้างการตอบกลับที่ตรงกับ schema เพื่อให้ทีม UI สามารถสร้างตารางโปสเตอร์ได้โดยไม่ต้องใช้โทเค็นสดหรือคำขอจริงที่กระทบขีดจำกัดของ TMDB

ขีดจำกัดอัตราและกฎการอ้างอิง

ทุกสิ่งที่อยู่ด้านล่างนี้อ้างอิงจากเอกสารของ TMDB

ขีดจำกัดอัตรา หน้าขีดจำกัดอัตรา ของ TMDB ระบุว่าขีดจำกัดเดิมที่ 40 คำขอทุก 10 วินาทีถูกปิดใช้งานเมื่อวันที่ 16 ธันวาคม 2019 ขีดจำกัดสูงสุดยังคงอยู่ “เพื่อช่วยลดการเก็บข้อมูลจำนวนมากที่ไม่จำเป็น” และ “อยู่ประมาณ 40 คำขอต่อวินาที” ตัวเลขนี้อาจเปลี่ยนแปลงได้โดยไม่ต้องแจ้งให้ทราบ ดังนั้นควรปฏิบัติตาม HTTP 429, ถอยกลับ และลองใหม่

ค่าใช้จ่าย จาก FAQ: “API ของเราใช้งานได้ฟรีสำหรับการใช้งานที่ไม่ใช่เชิงพาณิชย์ ตราบใดที่คุณให้เครดิต TMDB เป็นแหล่งที่มาของข้อมูลและ/หรือรูปภาพ” โปรเจกต์เชิงพาณิชย์ต้องติดต่อ sales@themoviedb.org

การอ้างอิง แสดงโลโก้ TMDB และประกาศนี้ในแอปพลิเคชันของคุณ: “ผลิตภัณฑ์นี้ใช้ TMDB API แต่ไม่ได้รับการรับรองหรือรับรองโดย TMDB” ข้อกำหนดการใช้งาน API ใช้ถ้อยคำที่ยาวกว่าเล็กน้อยและกำหนดให้โลโก้มีความโดดเด่นน้อยกว่าแบรนด์ของคุณเอง และห้ามเปลี่ยนสี, ยืด, พลิก หรือหมุน

การแคช ข้อกำหนดห้ามแคชข้อมูล TMDB ใดๆ เกินหกเดือน เก็บเท่าที่คุณต้องการ แต่ควรวางแผนการรีเฟรช

ไม่มี SLA TMDB กล่าวไว้อย่างชัดเจน สร้างการหมดเวลาและการลองใหม่

สุขอนามัยของคีย์ ข้อมูลรับรองทั้งสองควรอยู่ในตัวแปรสภาพแวดล้อมหรือตัวจัดการความลับ ห้ามอยู่ในซอร์สโค้ด หากมีสิ่งใดหลุดไปอยู่ใน repository ให้หมุนเวียนมันจากหน้าการตั้งค่าและรัน การตรวจสอบการรั่วไหลของคีย์ API ตลอดประวัติของคุณ

ข้อผิดพลาดทั่วไปและความหมายของมัน

TMDB ส่งคืนเนื้อหา JSON ที่มี status_code และ status_message ควบคู่ไปกับสถานะ HTTP ข้อมูลอ้างอิงข้อผิดพลาด แสดงรายการรหัสจำนวนมาก นี่คือรหัสที่คุณจะเห็นก่อน

คำถามที่พบบ่อย

คีย์ TMDB API ฟรีหรือไม่?

ใช่ สำหรับการใช้งานที่ไม่ใช่เชิงพาณิชย์พร้อมการอ้างอิง ไม่มีระดับการบริการตนเองแบบมีค่าใช้จ่าย หากโครงการของคุณสร้างรายได้ TMDB จะขอให้คุณจัดทำข้อตกลงเชิงพาณิชย์ผ่านทีมขายของพวกเขา

ฉันควรใช้คีย์ API หรือโทเค็นการเข้าถึงแบบอ่าน?

ใช้โทเค็นการเข้าถึงแบบอ่านเป็นส่วนหัว Bearer TMDB เรียกสิ่งนี้ว่าเป็นค่าเริ่มต้น ใช้งานได้ทั้ง v3 และ v4 และอยู่ห่างจาก URL ของคุณ คีย์ v3 มีไว้สำหรับเครื่องมือที่สามารถส่งพารามิเตอร์คิวรีได้เท่านั้น หากแนวคิดนี้ยังใหม่ บทนำเกี่ยวกับคีย์ API คืออะไร จะอธิบายรูปแบบที่ TMDB ใช้

ฉันสามารถเรียก TMDB โดยตรงจากเบราว์เซอร์หรือแอปพลิเคชันมือถือได้หรือไม่?

คุณทำได้ แต่สิ่งใดก็ตามที่ส่งไปยังไคลเอนต์จะเป็นสาธารณะ รวมถึงโทเค็นของคุณด้วย สำหรับโปรเจกต์ส่วนตัว ถือเป็นความเสี่ยงที่ยอมรับได้ สำหรับสิ่งที่มีผู้ใช้งาน ให้วางแบ็กเอนด์ขนาดเล็กหรือฟังก์ชัน serverless ไว้หน้า TMDB เก็บโทเค็นไว้ที่นั่น และแคชการค้นหายอดนิยม

ความแตกต่างระหว่าง v3 และ v4 คืออะไร?

v3 คือแคตตาล็อก: การค้นหา, รายละเอียดภาพยนตร์และทีวี, บุคคล, รูปภาพ, การค้นพบ v4 ครอบคลุมคุณสมบัติบัญชี เช่น รายการ, รายการโปรด, การให้คะแนน และรายการที่ต้องการดู และปลายทางสำหรับการเขียนต้องการโทเค็นการเข้าถึงของผู้ใช้ โทเค็นการเข้าถึงแบบอ่านของคุณใช้ในการรับรองความถูกต้องกับทั้งสองเวอร์ชัน

จะไปต่อที่ไหน

ตอนนี้คุณมีคีย์ TMDB API ที่ใช้งานได้, กฎสำหรับการส่งข้อมูลรับรองชุดใด, การค้นหาแล้วดูรายละเอียดใน curl และ Python, และการไหลเดียวกันที่บันทึกเป็นสถานการณ์ทดสอบ Apidog ถัดไป เพิ่ม discover/movie สำหรับการเรียกดูแบบกรอง และใส่ประกาศการอ้างอิงในแอปของคุณก่อนที่จะแชร์ ทุกอย่างอื่นๆ ในแคตตาล็อกใช้ URL พื้นฐาน, ส่วนหัว Bearer, และรูปแบบข้อผิดพลาดเดียวกัน