Вземете API ключ

Урок за C# и API за филми за .NET 8

Този урок изгражда конзолно приложение на .NET 8, което приема заглавие на филм, търси го в amodb, зарежда най-доброто съвпадение с рейтингите му и отпечатва кратка карта. Ползва само HttpClient и System.Text.Json, чете ключа от AMODB_KEY, повтаря при 429 и кешира отговорите във файлове. Настройката отнема около 15 минути.

.cs C# Обновено Отвори като Markdown

Какво изграждате

Изграждате MovieLookup, конзолно приложение, което приема заглавие от командния ред, търси го в amodb, зарежда най-доброто съвпадение с рейтингите му и отпечатва кратка карта с връзка към постер. Нужни са ви .NET 8 SDK, ключ за amodb и около 15 минути. Програмата ползва само HttpClient и System.Text.Json, така че няма NuGet пакети за инсталиране.

Стъпка 1: Вземете API ключ

Изберете план на страницата с цените. Плановете се различават само по скорост: 20, 40 или 120 заявки в минута. Създайте ключ в личния си профил, низ от 32 шестнайсетични символа с малки букви. Експортирайте го и го изпробвайте с едно извикване:

200 означава, че ключът работи. 401 означава, че ключът е грешен или липсва. В PowerShell задайте променливата с $env:AMODB_KEY = "YOUR_API_KEY". Страницата удостоверяване описва параметъра на заявката api_key като алтернатива на заглавката.

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"

Стъпка 2: Създайте проекта

Шаблонът на .NET 8 включва неявни using и nullable референтни типове. Това вече импортира System, System.IO, System.Linq и System.Net.Http. Останалите редове using добавяте във файла.

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

Стъпка 3: Изпратете първата заявка

Създайте един HttpClient с базов адрес, timeout от 10 секунди и заглавка Bearer. Завършете базовия адрес с наклонена черта, а относителните пътища пишете без водеща наклонена черта. Водеща черта би заменила частта /3 от базовия път.

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);

Стъпка 4: Преобразувайте JSON в records

Отговорът ползва имена в snake case, като release_date. Задайте JsonNamingPolicy.SnakeCaseLower, което е ново в .NET 8, и пишете членовете в PascalCase. Полетата, които не декларирате, се игнорират.

Обектът ratings се появява, защото извикването за детайли добавя append_to_response=ratings. Всеки от петте му източника е обект с value и votes или null, когато оценката липсва. votes също може да е null: живият отговор за Fight Club няма брой гласове за Kinopoisk, Metacritic или Rotten Tomatoes. Страницата филми изброява всички други полета.

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);

Стъпка 5: Обработка на грешки и лимити

Обвийте извикването в цикъл, който реагира на статус кода.

СтатусЗначениеКакво прави приложението
401Ключът липсва, е грешен или е спрянОтпечатва съобщение и спира, повторението не помага.
402Периодът на плана е изтекълОтпечатва съобщение и спира. Подновете от страницата с цените.
404Няма запис за това idДокладва и излиза.
429Надхвърлени заявки в минутаЧака Retry-After секунди, най-много 30, и повтаря най-много два пъти.
500 или 504Грешка от страна на сървъраДокладва статуса; стартирайте командата по-късно.

Мрежовите грешки излизат като HttpRequestException, а изтеклото време като TaskCanceledException. Хващайте и двете на най-горно ниво. Всеки отговор с ключ носи и X-RateLimit-Remaining, така че дълга задача може да забави ход, преди да стигне до 429. Пълните списъци са на страниците лимити на заявките и грешки.

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
}

Стъпка 6: Кеширайте отговорите на диска

Проверката на лимита се изпълнява преди edge кеша, така че отговор, обслужен от edge, пак се брои към заявките ви в минута. Кешът във вашата програма е единственият начин да спестите заявки. Edge държи детайлите 6 часа, а резултатите от търсене 10 минути, затова приложението ползва същите срокове. Файл във временната папка е свеж, когато времето на запис е в рамките на 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;
    }
}

Стъпка 7: Съберете всичко

Това е цялата Program.cs. Тя добавя метода Set към кеша и класа AmodbClient, който обединява кеша, цикъла за повторения и 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)!;
        }
    }
}

Стартирайте я със заглавие. Това е изходът за първото намерено съвпадение, филм 550. Броят гласове расте с времето, така че вашият ще се различава малко.

Редът за TMDB показва 8.4, защото кодът отпечатва един десетичен знак от 8.437 в ratings.tmdb.value. Хостът за постери img.amodb.dev не иска ключ, така че можете да подадете URL адреса на постера направо на браузър или контрола за изображение. Списъкът с размери е на страницата изображения.

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

Следващи стъпки

  • Търсете с година или странициране в търсене и филтрирайте списъци с откриване по филтри.
  • Показвайте всяка оценка и правилата за null с рейтинги.
  • Преместете конзолния код в услуга на ASP.NET Core с AddHttpClient и IMemoryCache.
  • Сравнете същата задача на Java или Go.