SDK .NET | Evocrawl

Installation

Le SDK .NET officiel est maintenu dans le monorepo de Evocrawl à l’emplacement apps/.net-sdk. Pour installer le SDK .NET de Evocrawl, ajoutez le package NuGet :

.NET CLI
Gestionnaire de packages
PackageReference

bash dotnet add package evocrawl-sdk

powershell Install-Package evocrawl-sdk

<PackageReference Include="evocrawl-sdk" Version="1.0.0" />

Nécessite .NET 8.0 ou une version ultérieure.

Utilisation

Obtenez une clé API sur evocrawl.dev
Définissez la clé API comme variable d’environnement nommée EVOCRAWL_API_KEY, ou passez-la au constructeur EvocrawlClient

Voici un exemple rapide avec l’API actuelle du SDK :

using Evocrawl;
using Evocrawl.Models;

var client = new EvocrawlClient("fc-your-api-key");

// Scraper une seule page
var doc = await client.ScrapeAsync("https://evocrawl.com",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

// Crawler un site web
var job = await client.CrawlAsync("https://evocrawl.com",
    new CrawlOptions { Limit = 5 });

Console.WriteLine(doc.Markdown);
Console.WriteLine($"Crawled pages: {job.Data?.Count ?? 0}");

Scraping d’une URL

Pour effectuer le scraping d’une seule URL, utilisez la méthode ScrapeAsync.

using Evocrawl.Models;

var doc = await client.ScrapeAsync("https://evocrawl.com",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown", "html" },
        OnlyMainContent = true,
        WaitFor = 5000
    });

Console.WriteLine(doc.Markdown);
Console.WriteLine(doc.Metadata?["title"]);

Extraction de JSON

Extrayez des données JSON structurées avec JsonFormat via le point de terminaison scrape :

using Evocrawl.Models;

var jsonFmt = new JsonFormat
{
    Prompt = "Extract the product name and price",
    Schema = new Dictionary<string, object>
    {
        ["type"] = "object",
        ["properties"] = new Dictionary<string, object>
        {
            ["name"] = new Dictionary<string, object> { ["type"] = "string" },
            ["price"] = new Dictionary<string, object> { ["type"] = "number" }
        }
    }
};

var doc = await client.ScrapeAsync("https://example.com/product",
    new ScrapeOptions
    {
        Formats = new List<object> { jsonFmt }
    });

Console.WriteLine(doc.Json);

Effectuer un crawl sur un site web

Pour effectuer un crawl sur un site web et attendre la fin de l’opération, utilisez CrawlAsync. Cette méthode gère automatiquement l’interrogation et la pagination.

using Evocrawl.Models;

var job = await client.CrawlAsync("https://evocrawl.com",
    new CrawlOptions
    {
        Limit = 50,
        MaxDiscoveryDepth = 3,
        ScrapeOptions = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Console.WriteLine($"Status: {job.Status}");
Console.WriteLine($"Progress: {job.Completed}/{job.Total}");

if (job.Data != null)
{
    foreach (var page in job.Data)
    {
        Console.WriteLine(page.Metadata?["sourceURL"]);
    }
}

Démarrer un crawl

Lancez une tâche sans attendre avec StartCrawlAsync.

using Evocrawl.Models;

var start = await client.StartCrawlAsync("https://evocrawl.com",
    new CrawlOptions { Limit = 100 });

Console.WriteLine($"Job ID: {start.Id}");

Vérifier l’état du crawl

Consultez la progression du crawl avec GetCrawlStatusAsync.

var status = await client.GetCrawlStatusAsync(start.Id!);
Console.WriteLine($"Status: {status.Status}");
Console.WriteLine($"Progress: {status.Completed}/{status.Total}");

Annuler un crawl

Annulez un crawl en cours avec CancelCrawlAsync.

var result = await client.CancelCrawlAsync(start.Id!);
Console.WriteLine(result);

Cartographier un site web

Découvrez les liens d’un site avec MapAsync.

using Evocrawl.Models;

var data = await client.MapAsync("https://evocrawl.com",
    new MapOptions
    {
        Limit = 100,
        Search = "blog"
    });

if (data.Links != null)
{
    foreach (var link in data.Links)
    {
        Console.WriteLine(link);
    }
}

Recherche sur le Web

Effectuez une recherche avec des paramètres facultatifs via SearchAsync.

using Evocrawl.Models;

var results = await client.SearchAsync("evocrawl web scraping",
    new SearchOptions
    {
        Limit = 10,
        Location = "US"
    });

if (results.Web != null)
{
    foreach (var hit in results.Web)
    {
        Console.WriteLine($"{hit.Title} - {hit.Url}");
    }
}

Scraping par lots

Scrapez plusieurs URL en parallèle à l’aide de BatchScrapeAsync. Cette méthode gère automatiquement l’interrogation et la pagination.

using Evocrawl.Models;

var urls = new List<string>
{
    "https://evocrawl.com",
    "https://evocrawl.com/blog"
};

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

if (job.Data != null)
{
    foreach (var doc in job.Data)
    {
        Console.WriteLine(doc.Markdown);
    }
}

Extraction par lot avec clé d’idempotence

Pour éviter que des requêtes en double ne soient traitées, fournissez une IdempotencyKey :

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        IdempotencyKey = "my-unique-key",
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Utilisation & métriques

Vérifier la concurrence et les crédits restants :

using Evocrawl.Models;

var concurrency = await client.GetConcurrencyAsync();
Console.WriteLine($"Concurrency: {concurrency.Current}/{concurrency.MaxConcurrency}");

var credits = await client.GetCreditUsageAsync();
Console.WriteLine($"Remaining credits: {credits.RemainingCredits}");

Compatibilité async

Toutes les méthodes du SDK .NET sont async par défaut et renvoient Task<T>. Elles prennent également en charge CancellationToken pour permettre une annulation coopérative.

using Evocrawl.Models;

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown" }
    },
    cancellationToken: cts.Token);

Console.WriteLine(doc.Markdown);

Configuration

Le constructeur EvocrawlClient accepte les options suivantes :

Option	Type	Par défaut	Description
`apiKey`	`string?`	variable d’environnement `EVOCRAWL_API_KEY`	Votre clé API Evocrawl
`apiUrl`	`string?`	`https://api.evocrawl.com` (ou `EVOCRAWL_API_URL`)	URL de base de l’API
`timeout`	`TimeSpan?`	5 minutes	Délai d’expiration de la requête HTTP
`maxRetries`	`int`	`3`	Nouvelles tentatives automatiques en cas d’échecs temporaires
`backoffFactor`	`double`	`0.5`	Facteur de backoff exponentiel en secondes
`httpClient`	`HttpClient?`	Créé à partir de `timeout`	Instance HttpClient préconfigurée

using Evocrawl;

var client = new EvocrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://api.evocrawl.com",
    timeout: TimeSpan.FromMinutes(5),
    maxRetries: 3,
    backoffFactor: 0.5);

Client HTTP personnalisé

Vous pouvez transmettre un HttpClient préconfiguré pour contrôler le pool de connexions, les proxys, les gestionnaires de messages et toute autre fonctionnalité de HttpClient. Lorsqu’il est fourni, le paramètre timeout est ignoré au profit de la configuration du client lui-même.

using Evocrawl;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
    UseProxy = true
};

var httpClient = new HttpClient(handler)
{
    Timeout = TimeSpan.FromSeconds(60)
};

var client = new EvocrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);

Configuration des variables d’environnement

Le SDK détermine sa configuration à partir des variables d’environnement lorsque les paramètres du constructeur ne sont pas fournis :

// Utilise les variables d'environnement EVOCRAWL_API_KEY et EVOCRAWL_API_URL
var client = new EvocrawlClient();

Gestion des erreurs

Le SDK génère des exceptions spécifiques dans Evocrawl.Exceptions.

using Evocrawl.Exceptions;
using Evocrawl.Models;

try
{
    var doc = await client.ScrapeAsync("https://example.com");
}
catch (AuthenticationException ex)
{
    Console.Error.WriteLine($"Auth failed: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.Error.WriteLine($"Rate limited: {ex.Message}");
}
catch (JobTimeoutException ex)
{
    Console.Error.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");
}
catch (EvocrawlException ex)
{
    Console.Error.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
}

La hiérarchie des exceptions :

Exception	Code HTTP	Quand
`AuthenticationException`	401	Clé API invalide ou manquante
`RateLimitException`	429	Trop de requêtes
`JobTimeoutException`	—	La tâche asynchrone (crawl/extraction par lot) n’a pas été terminée à temps
`EvocrawlException`	variable	Exception de base pour toutes les autres erreurs de l’API

Les échecs transitoires (408, 409, 502 et autres erreurs 5xx) sont automatiquement retentés avec un backoff exponentiel avant qu’une exception ne soit levée.

Êtes-vous un agent IA ayant besoin d’une clé API Evocrawl ? Consultez evocrawl.dev/agent-onboarding/SKILL.md pour les instructions d’intégration automatisée.

Global

Officiel

.NET

Installation

Utilisation

Scraping d’une URL

Extraction de JSON

Effectuer un crawl sur un site web

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Recherche sur le Web

Scraping par lots

Extraction par lot avec clé d’idempotence

Utilisation & métriques

Compatibilité async

Configuration

Client HTTP personnalisé

Configuration des variables d’environnement

Gestion des erreurs

​Installation

​Utilisation

​Scraping d’une URL

​Extraction de JSON

​Effectuer un crawl sur un site web

​Démarrer un crawl

​Vérifier l’état du crawl

​Annuler un crawl

​Cartographier un site web

​Recherche sur le Web

​Scraping par lots

​Extraction par lot avec clé d’idempotence

​Utilisation & métriques

​Compatibilité async

​Configuration

​Client HTTP personnalisé

​Configuration des variables d’environnement

​Gestion des erreurs

Installation

Utilisation

Scraping d’une URL

Extraction de JSON

Effectuer un crawl sur un site web

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Recherche sur le Web

Scraping par lots

Extraction par lot avec clé d’idempotence

Utilisation & métriques

Compatibilité async

Configuration

Client HTTP personnalisé

Configuration des variables d’environnement

Gestion des erreurs