Pobierz klucz API

Poradnik API filmów w C# dla .NET 8

Ten poradnik buduje aplikację konsolową .NET 8, która przyjmuje tytuł filmu, wyszukuje go w amodb, pobiera najlepsze dopasowanie wraz z ocenami i wypisuje krótką kartę. Używa tylko HttpClient i System.Text.Json, czyta klucz z AMODB_KEY, ponawia żądanie po 429 i zapisuje odpowiedzi w plikach. Konfiguracja zajmuje około 15 minut.

.cs C# Zaktualizowano Zobacz jako Markdown

Co zbudujesz

Zbudujesz MovieLookup, aplikację konsolową, która przyjmuje tytuł z wiersza poleceń, wyszukuje go w amodb, pobiera najlepsze dopasowanie wraz z ocenami i wypisuje krótką kartę z linkiem do plakatu. Potrzebujesz .NET 8 SDK, klucza amodb i około 15 minut. Program używa tylko HttpClient i System.Text.Json, więc nie instalujesz żadnych pakietów NuGet.

Krok 1: Zdobądź klucz API

Wybierz plan na stronie cennik. Plany różnią się tylko szybkością, a to 20, 40 lub 120 żądań na minutę. Utwórz klucz w panelu konta, to ciąg 32 małych znaków szesnastkowych. Wyeksportuj go i sprawdź jednym wywołaniem:

200 oznacza, że klucz działa. 401 oznacza, że klucz jest błędny lub go brakuje. W PowerShell ustaw zmienną przez $env:AMODB_KEY = "YOUR_API_KEY". Strona uwierzytelnianie opisuje parametr zapytania api_key jako alternatywę dla nagłówka.

Shell 
export AMODB_KEY=YOUR_API_KEY
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $AMODB_KEY" \
  "https://api.amodb.dev/3/movie/550"

Krok 2: Utwórz projekt

Szablon .NET 8 włącza niejawne using i nullable reference types. To już importuje System, System.IO, System.Linq i System.Net.Http. Pozostałe linie using dodajesz w pliku.

Shell 
dotnet new console -n MovieLookup -f net8.0
cd MovieLookup

Krok 3: Wyślij pierwsze żądanie

Utwórz jeden HttpClient z adresem bazowym, 10-sekundowym timeoutem i nagłówkiem Bearer. Zakończ adres bazowy ukośnikiem i pisz ścieżki względne bez ukośnika na początku. Ukośnik na początku zastąpiłby część /3 ścieżki bazowej.

C# 
using System.Net.Http.Headers;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://api.amodb.dev/3/"),
    Timeout = TimeSpan.FromSeconds(10),
};
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AMODB_KEY"));

var response = await http.GetAsync("search/movie?query=fight%20club&language=en-US");
Console.WriteLine((int)response.StatusCode);

Krok 4: Zamień JSON na rekordy

Odpowiedź używa nazw w snake case, takich jak release_date. Ustaw JsonNamingPolicy.SnakeCaseLower, nowe w .NET 8, i pisz składowe w PascalCase. Pola, których nie zadeklarujesz, są ignorowane.

Obiekt ratings pojawia się, bo wywołanie szczegółów dodaje append_to_response=ratings. Każde z jego pięciu źródeł to obiekt z value i votes albo null, gdy brakuje wyniku. votes też może być null: rzeczywista odpowiedź dla Fight Club nie ma liczby głosów dla Kinopoisk, Metacritic ani Rotten Tomatoes. Wszystkie pozostałe pola wymienia strona filmy.

C# 
record SearchResponse(List<SearchHit> Results);
record SearchHit(int Id, string Title, string? ReleaseDate);
record Movie(int Id, string Title, string? Tagline, string? ReleaseDate, int? Runtime,
    string? PosterPath, double VoteAverage, RatingSet? Ratings);
record RatingSet(Score? Imdb, Score? Kinopoisk, Score? Metacritic, Score? RottenTomatoes, Score? Tmdb);
record Score(double Value, int? Votes);

Krok 5: Obsłuż błędy i limity żądań

Obejmij wywołanie pętlą, która reaguje na kod statusu.

StatusZnaczenieCo robi aplikacja
401Brak klucza, jest błędny lub zawieszonyWypisuje komunikat i kończy, ponowienie nie pomoże.
402Okres planu dobiegł końcaWypisuje komunikat i kończy. Odnów go na stronie cennik.
404Brak rekordu dla tego IDZgłasza to i kończy.
429Przekroczono żądania na minutęCzeka Retry-After sekund, maksymalnie 30, i ponawia najwyżej dwa razy.
500 lub 504Awaria po stronie serweraZgłasza status, uruchom polecenie ponownie później.

Błędy sieci pojawiają się jako HttpRequestException, a timeout jako TaskCanceledException. Przechwyć oba na najwyższym poziomie. Każda odpowiedź z kluczem niesie też X-RateLimit-Remaining, więc długie zadanie może zwolnić, zanim dojdzie do 429. Pełne listy znajdziesz na stronach limity żądań i błędy.

C# 
for (var attempt = 0; ; attempt++)
{
    using var response = await http.GetAsync(path);
    if (response.StatusCode == HttpStatusCode.TooManyRequests && attempt < 2)
    {
        var seconds = Math.Min(response.Headers.RetryAfter?.Delta?.TotalSeconds ?? 5, 30);
        await Task.Delay(TimeSpan.FromSeconds(seconds));
        continue;
    }
    if (response.StatusCode == HttpStatusCode.Unauthorized)
        throw new AmodbException("The API key was rejected (401). Check AMODB_KEY.");
    // ...handle other statuses, then read the body
}

Krok 6: Zapisuj odpowiedzi na dysku

Sprawdzenie limitu działa przed cache na edge, więc odpowiedź podana z edge nadal liczy się do twoich żądań na minutę. Cache we własnym programie to jedyny sposób na oszczędzanie żądań. Edge trzyma szczegóły przez 6 godzin, a wyniki wyszukiwania przez 10 minut, więc aplikacja używa tych samych czasów życia. Plik w folderze temp jest świeży, gdy jego czas zapisu mieści się w TTL.

C# 
class FileCache
{
    readonly string dir = Path.Combine(Path.GetTempPath(), "amodb-cache");

    string PathFor(string key) =>
        Path.Combine(dir, Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(key))) + ".json");

    public string? Get(string key, TimeSpan ttl)
    {
        var file = PathFor(key);
        return File.Exists(file) && DateTime.UtcNow - File.GetLastWriteTimeUtc(file) < ttl
            ? File.ReadAllText(file)
            : null;
    }
}

Krok 7: Złóż całość

To kompletny Program.cs. Dodaje do cache metodę Set oraz klasę AmodbClient, która łączy cache, pętlę ponowień i opcje JSON.

C# 
using System.Globalization;
using System.Net;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

CultureInfo.CurrentCulture = CultureInfo.InvariantCulture; // same number format on every machine

var key = Environment.GetEnvironmentVariable("AMODB_KEY");
if (string.IsNullOrWhiteSpace(key))
{
    Console.Error.WriteLine("Set AMODB_KEY first.");
    return 1;
}

var title = string.Join(' ', args).Trim();
if (title.Length == 0)
{
    Console.Error.WriteLine("Usage: dotnet run -- \"movie title\"");
    return 1;
}

using var http = new HttpClient
{
    BaseAddress = new Uri("https://api.amodb.dev/3/"),
    Timeout = TimeSpan.FromSeconds(10),
};
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);
var client = new AmodbClient(http, new FileCache());

try
{
    var search = await client.GetAsync<SearchResponse>(
        $"search/movie?query={Uri.EscapeDataString(title)}&language=en-US", TimeSpan.FromMinutes(10));
    var hit = search.Results.FirstOrDefault();
    if (hit is null)
    {
        Console.WriteLine($"No movie found for \"{title}\".");
        return 0;
    }

    var movie = await client.GetAsync<Movie>(
        $"movie/{hit.Id}?language=en-US&append_to_response=ratings", TimeSpan.FromHours(6));
    Print(movie);
    return 0;
}
catch (AmodbException ex)
{
    Console.Error.WriteLine(ex.Message);
    return 1;
}
catch (HttpRequestException ex)
{
    Console.Error.WriteLine($"Network error: {ex.Message}");
    return 1;
}
catch (TaskCanceledException)
{
    Console.Error.WriteLine("The request timed out after 10 seconds.");
    return 1;
}

static void Print(Movie m)
{
    var year = m.ReleaseDate is { Length: >= 4 } d ? d[..4] : "n/a";
    Console.WriteLine($"{m.Title} ({year}), {m.Runtime?.ToString() ?? "?"} min");
    if (!string.IsNullOrEmpty(m.Tagline)) Console.WriteLine(m.Tagline);
    Console.WriteLine($"IMDb: {Describe(m.Ratings?.Imdb)}");
    Console.WriteLine($"TMDB: {Describe(m.Ratings?.Tmdb)}");
    if (m.PosterPath is not null)
        Console.WriteLine($"Poster: https://img.amodb.dev/t/p/w342{m.PosterPath}");
}

static string Describe(Score? s) =>
    s is null ? "not known" : $"{s.Value:0.0}" + (s.Votes is { } v ? $" ({v:N0} votes)" : "");

record SearchResponse(List<SearchHit> Results);
record SearchHit(int Id, string Title, string? ReleaseDate);
record Movie(int Id, string Title, string? Tagline, string? ReleaseDate, int? Runtime,
    string? PosterPath, double VoteAverage, RatingSet? Ratings);
record RatingSet(Score? Imdb, Score? Kinopoisk, Score? Metacritic, Score? RottenTomatoes, Score? Tmdb);
record Score(double Value, int? Votes);

class AmodbException : Exception
{
    public AmodbException(string message) : base(message) { }
}

class FileCache
{
    readonly string dir = Path.Combine(Path.GetTempPath(), "amodb-cache");

    string PathFor(string key) =>
        Path.Combine(dir, Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(key))) + ".json");

    public string? Get(string key, TimeSpan ttl)
    {
        var file = PathFor(key);
        return File.Exists(file) && DateTime.UtcNow - File.GetLastWriteTimeUtc(file) < ttl
            ? File.ReadAllText(file)
            : null;
    }

    public void Set(string key, string json)
    {
        Directory.CreateDirectory(dir);
        File.WriteAllText(PathFor(key), json);
    }
}

class AmodbClient(HttpClient http, FileCache cache)
{
    static readonly JsonSerializerOptions Options = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
    };

    public async Task<T> GetAsync<T>(string path, TimeSpan ttl)
    {
        var cached = cache.Get(path, ttl);
        if (cached is not null) return JsonSerializer.Deserialize<T>(cached, Options)!;

        for (var attempt = 0; ; attempt++)
        {
            using var response = await http.GetAsync(path);
            if (response.StatusCode == HttpStatusCode.TooManyRequests && attempt < 2)
            {
                var seconds = Math.Min(response.Headers.RetryAfter?.Delta?.TotalSeconds ?? 5, 30);
                await Task.Delay(TimeSpan.FromSeconds(seconds));
                continue;
            }
            if (response.StatusCode == HttpStatusCode.Unauthorized)
                throw new AmodbException("The API key was rejected (401). Check AMODB_KEY.");
            if (!response.IsSuccessStatusCode)
                throw new AmodbException($"amodb returned status {(int)response.StatusCode}.");

            var body = await response.Content.ReadAsStringAsync();
            cache.Set(path, body);
            return JsonSerializer.Deserialize<T>(body, Options)!;
        }
    }
}

Uruchom go z tytułem. To wynik dla pierwszego trafienia wyszukiwania, filmu 550. Liczby głosów rosną z czasem, więc twoje będą się trochę różnić.

Linia TMDB pokazuje 8.4, bo kod wypisuje jedno miejsce po przecinku z 8.437 w ratings.tmdb.value. Host plakatów img.amodb.dev nie wymaga klucza, więc możesz przekazać URL plakatu prosto do przeglądarki lub kontrolki obrazu. Listę rozmiarów znajdziesz w obrazy.

Shell 
dotnet run -- "fight club"
# Fight Club (1999), 139 min
# Mischief. Mayhem. Soap.
# IMDb: 8.8 (2,669,989 votes)
# TMDB: 8.4 (33,039 votes)
# Poster: https://img.amodb.dev/t/p/w342/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg

Kolejne kroki

  • Szukaj z rokiem lub paginacją na stronie wyszukiwanie i filtruj listy przez discover.
  • Pokaż każdy wynik i jego reguły null na stronie oceny.
  • Przenieś kod konsolowy do usługi ASP.NET Core z AddHttpClient i IMemoryCache.
  • Porównaj to samo zadanie w Java lub Go.