Dans cet article de blog, vous découvrirez :
- Ce qu’est la spécification OpenAPI.
- Pourquoi elle est si populaire pour la définition d’outils dans les cadres et les plateformes d’IA.
- Comment Bright Data prend en charge OpenAPI pour une intégration simplifiée dans les agents et les flux de travail IA.
- La spécification OpenAPI de l’API Bright Data Web Unlocker.
- La spécification OpenAPI de l’API SERP de Bright Data.
- Comment ces spécifications fonctionnent dans la pratique au sein d’une plateforme d’IA réelle
Plongeons-nous dans le vif du sujet !
Qu’est-ce que la spécification OpenAPI ?
La spécification OpenAPI (OAS) est une norme ouverte, indépendante du langage, qui permet de décrire les API RESTful. Elle fournit un format structuré et lisible par machine (généralement YAML ou JSON) pour définir les opérations, les paramètres, les réponses, les schémas de sécurité et d’autres caractéristiques d’une API.
Découvrez le référentiel GitHub pour la spécification!
Remarque: la spécification OpenAPI s’appelait à l’origine « spécification Swagger ». Si vous recherchez les « spécifications Swagger de Bright Data », vous êtes au bon endroit !
Pourquoi de nombreuses solutions d’IA s’appuient sur les spécifications OpenAPI pour la définition des outils
De nombreux frameworks d’IA adoptent la prise en charge OpenAPI pour la définition des outils. La raison principale est que la spécification OpenAPI fournit un contrat standardisé et lisible par machine qui décrit exactement ce que fait une API externe.
Cette normalisation offre trois avantages principaux :
- Interopérabilité et friction minimale: OpenAPI est une norme largement prise en charge. Une fois que vous fournissez une spécification, la plateforme peut importer automatiquement l’API, générer des formulaires de saisie, des appels et des traitements de réponse, et l’intégrer à ses outils.
- Réduction de la courbe d’apprentissage: même les utilisateurs non techniques peuvent créer des outils à l’aide d’API en copiant simplement les spécifications OpenAPI à partir de la documentation ou d’autres sources. Il n’est donc pas nécessaire de procéder à un câblage ou à un codage manuel, ce qui explique pourquoi la prise en charge d’OpenAPI est si courante dans les plateformes d’IA à faible ou sans code.
- Meilleure maintenance: grâce à un contrat API explicite, les mises à jour sont faciles. Lorsque l’API évolue, il suffit de mettre à jour la spécification dans la définition de l’outil, ce qui simplifie considérablement la maintenance et réduit le besoin de réécritures importantes.
En bref, la définition d’outils via OpenAPI ouvre la voie à un écosystème prêt à l’emploi pour les entreprises, dans lequel les CRM, les fournisseurs de données, les API internes et d’autres services externes peuvent être connectés, documentés et maintenus en toute sécurité avec un minimum de frais généraux manuels dans les agents, les pipelines et les flux de travail IA.
Présentation des spécifications OpenAPI de Bright Data
Bright Data propose une suite de produits et de services pour l’extraction de données web, l’interaction web automatisée, le crawling web et bien plus encore.
Ces solutions sont disponibles via des API (et également via des options sans code), ce qui signifie que vous pouvez les configurer à l’aide des spécifications OpenAPI dans les plateformes d’IA qui prennent en charge cette fonctionnalité.
Dans cet article, nous nous concentrerons sur deux des outils Bright Data les plus importants :
- API SERP: extrait automatiquement des données structurées à partir de moteurs de recherche tels que Google, Bing et Yandex. Elle gère des tâches complexes telles que la gestion des Proxys, la Résolution de CAPTCHA et le rendu JavaScript, vous permettant d’obtenir des résultats propres et en temps réel au format JSON ou HTML sans être bloqué.
- API Web Unlocker: contourne les mesures anti-bot complexes (telles que les CAPTCHA, les blocages d’IP et les empreintes digitales) pour extraire les données web de n’importe quelle page web. Elle agit comme un intermédiaire, gérant les Proxies, émulant les utilisateurs réels et fournissant des réponses HTML, JSON et Markdown propres.
Pour chaque service, vous verrez la spécification OpenAPI 3.x aux formats YAML et JSON, ainsi que des exemples de tests dans Swagger Editor.
À partir de ces spécifications, vous pouvez de la même manière convertir les API de Scraping web et d’autres points de terminaison API en spécifications OpenAPI pour l’intégration de l’IA.
Remarque: certains produits Bright Data partagent les mêmes points de terminaison API, modifiant leur comportement uniquement en fonction du corps de la requête. Comme vous ne pouvez pas définir deux spécifications complètement distinctes pour le même chemin et la même méthode dans un seul document OpenAPI, vous avez besoin de spécifications OpenAPI distinctes. C’est pourquoi nous fournirons deux spécifications OpenAPI dédiées pour l’API SERP et l’API Web Unlocker (car elles partagent le même point de terminaison).
Spécification OpenAPI de l’API Web Unlocker
Découvrez la spécification OpenAPI pour l’API Web Unlocker de Bright Data.
Remarque: pour plus de détails, consultez les arguments, options, méthodes d’authentification et autres informations disponibles dans les pages de documentation suivantes :
Spécification YAML
Voici la spécification OpenAPI YAML pour l’API Web Unlocker de Bright Data :
openapi: 3.0.4
info:
title: API Web Unlocker de Bright Data
version: 1.0.0
description: |
L'API Web Unlocker de Bright Data vous permet de contourner les mesures anti-bot, de gérer les Proxy et de réaliser la résolution automatique des CAPTCHA pour faciliter la collecte de données sur le Web.
[Documentation de l'API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)
contact :
nom : Bright Data
url :
serveurs :
- url : https://api.brightdata.com
balises :
- nom : Web Unlocker
description : Opérations pour interagir avec l'API Bright Data Web Unlocker.
composants :
securitySchemes :
BearerAuth :
type : http
scheme : bearer
bearerFormat : BRIGHT_DATA_API_KEY
chemins :
/request :
post :
operationId : sendWebUnlockerRequest
summary : Envoyer une requête API Web Unlocker
description : |
Envoyer une requête API Web Unlocker à l'aide de votre zone API Bright Data Web Unlocker.
[Documentation API Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)
balises :
- Web Unlocker
sécurité :
- BearerAuth : []
requestBody :
requis : vrai
contenu :
application/json :
schéma :
type : objet
requis :
- zone
- url
- format
propriétés :
zone :
type : chaîne
description : nom de votre zone Web Unlocker.
url :
type : chaîne
description : URL du site Web cible à déverrouiller et à récupérer.
exemple : https://example.com/products
format :
type : chaîne
description : |
Format de réponse.
Valeurs autorisées :
- `raw` : renvoie immédiatement la réponse dans le corps.
- `json` : renvoie la réponse sous forme d'objet JSON structuré.
par défaut : raw
méthode :
type : chaîne de caractères
description : Méthode HTTP utilisée lors de la récupération de l'URL cible.
exemple : GET
pays :
type : chaîne de caractères
description : |
Code pays pour l'emplacement du Proxy (format ISO 3166-1 alpha-2).
exemple : us
format_des_données :
type : chaîne de caractères
description : |
Format des données de sortie extraites.
Valeurs autorisées :
- `markdown` : contenu de la page converti en Markdown.
- `screenshot` : pour capturer une image PNG de la page rendue.
énumération :
- markdown
- screenshot
réponses :
« 200 » :
description : réponse réussie contenant les résultats de la recherche.
« 400 » :
description : demande non valide (champs obligatoires manquants ou paramètres non valides).
« 401 » :
description : non autorisé (clé API Bright Data non valide ou manquante).Remarque:
La section securitySchemes spécifie un schéma de sécurité qui utilise l’authentification HTTP bearer. Plus précisément, les clients doivent envoyer une BRIGHT_DATA_API_KEY en tant que jeton bearer dans l’en-tête Authorization lorsqu’ils appellent l’API.
Dans le même temps, la plupart des plateformes d’IA intègrent déjà des méthodes d’authentification et peuvent ignorer ce champ de spécification. Il est toutefois utile de l’inclure dans la spécification OpenAPI pour plus de clarté et à titre de référence.
Spécification JSON
Vous trouverez ci-dessous la spécification JSON OpenAPI pour l’API Web Unlocker :
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data Web Unlocker API",
"version": "1.0.0",
"description": "Bright Data Web Unlocker API vous permet de contourner les mesures anti-bot, de gérer les Proxys et de réaliser la résolution automatique de CAPTCHA pour faciliter la collecte de données sur le Web.nn[Documentation de l'API Web Unlocker](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
},
« servers » : [
{
« url » : « https://api.brightdata.com »
}
],
« tags » : [
{
« name » : « Web Unlocker »,
« description » : « Opérations pour interagir avec l'API Bright Data Web Unlocker. »
}
],
« components » : {
« securitySchemes » : {
« BearerAuth » : {
« type » : « http »,
« scheme » : « bearer »,
« bearerFormat » : « BRIGHT_DATA_API_KEY »
}
}
},
"paths": {
"/request" : {
"post" : {
"operationId" : "sendWebUnlockerRequest",
"summary" : "Envoyer une requête API Web Unlocker",
"description" : "Soumettre une requête API Web Unlocker à l'aide de votre zone API Bright Data Web Unlocker. nn[Documentation de l'API Web Unlocker `/request`](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)n",
"tags": [
"Web Unlocker"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"Zone",
"url",
« format »
],
« properties » : {
« zone » : {
« type » : « string »,
« description » : « Nom de votre zone Web Unlocker. »
},
« url » : {
« type » : « string »,
« description » : « URL du site Web cible à déverrouiller et à récupérer. »,
« example » : « https://example.com/products »
},
« format » : {
« type » : « string »,
« description » : « Format de réponse. nValeurs autorisées : n- `raw` : renvoie immédiatement la réponse dans le corps. n- `json` : renvoie la réponse sous forme d'objet JSON structuré. n »,
« default » : « raw »
},
« method » : {
« type » : « string »,
« description » : « Méthode HTTP utilisée lors de la récupération de l'URL cible. »,
« example » : « GET »
},
« country » : {
« type » : « string »,
« description » : « Code pays pour l'emplacement du Proxy (format ISO 3166-1 alpha-2). n »,
« example » : « us »
},
"data_format" : {
"type" : "string",
"description" : "Format des données de sortie extraites. nValeurs autorisées : n- `markdown` : contenu de la page converti en Markdown.n- `screenshot` : pour capturer une image PNG de la page rendue.n",
"enum": [
"markdown",
"screenshot"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Réponse réussie contenant les résultats de la recherche."
},
"400": {
"description": "Demande non valide (champs obligatoires manquants ou paramètres non valides)."
},
"401": {
"description": "Non autorisé (clé API Bright Data invalide ou manquante)."
}
}
}
}
}
}Test dans Swagger Editor
Testez la spécification OpenAPI en la collant dans Swagger Editor:
Spécification OpenAPI de l’API SERP
Découvrez la spécification OpenAPI pour l’API SERP de Bright Data.
Remarque: pour plus d’informations, consultez les arguments, les options, les méthodes d’authentification et plus encore dans les pages de documentation suivantes :
Spécification YAML
Voici la spécification OpenAPI YAML pour l’API SERP :
openapi: 3.0.4
info:
title: API SERP Bright Data
version: 1.0.0
description: |
Extrayez les résultats des moteurs de recherche à l'aide de l'API SERP Bright Data. Extrayez des données structurées des principaux moteurs de recherche, notamment Google, Bing, Yandex, DuckDuckGo et bien d'autres.
Obtenez des résultats organiques, des publicités payantes, des listes locales, des résultats d'achat et d'autres fonctionnalités SERP.
[Documentation de l'API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)
contact :
nom : Bright Data
url :
serveurs :
- url : https://api.brightdata.com
balises :
- nom : SERP
description : Opérations liées à l'API SERP de Bright Data.
composants :
securitySchemes :
BearerAuth :
type : http
scheme : bearer
bearerFormat : BRIGHT_DATA_API_KEY
chemins :
/request :
post :
operationId : sendSerpRequest
summary : Envoyer une requête API SERP
description : |
Soumettre une requête API SERP à l'aide de votre zone API SERP Bright Data.
[Documentation API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)
tags :
- SERP
sécurité :
- BearerAuth : []
requestBody :
obligatoire : vrai
contenu :
application/json :
schéma :
type : objet
obligatoire :
- zone
- url
- format
propriétés :
zone :
type : chaîne
description : le nom de votre zone API SERP.
url :
type : chaîne
description : URL du moteur de recherche à interroger (par exemple, `https://www.google.com/search?q=<search_query>`).
exemple : https://www.google.com/search?q=pizza&hl=en&gl=us
format :
type : chaîne
description : |
Format de réponse.
Valeurs autorisées :
- `raw` : renvoie immédiatement la réponse dans le corps.
- `json` : renvoie la réponse sous forme d'objet JSON structuré.
par défaut : raw
énumération :
- raw
- json
pays :
type : chaîne de caractères
description : |
Code pays pour l'emplacement du Proxy (format ISO 3166-1 alpha-2).
exemple : us
data_format :
type : chaîne de caractères
description : |
Format des données de sortie SERP.
Valeurs autorisées :
- `json` : données JSON entièrement analysées avec des résultats SERP structurés, y compris des extraits organiques, payants, locaux, commerciaux et de fonctionnalités.
- `markdown` : contenu SERP converti en Markdown.
énumération :
- json
- markdown
réponses :
« 200 » :
description : réponse réussie contenant les résultats de recherche.
« 400 » :
description : requête non valide (champs obligatoires manquants ou paramètres non valides).
« 401 » :
description : non autorisé (clé API Bright Data invalide ou manquante).Spécification JSON
Voici la spécification JSON OpenAPI pour l’API SERP :
{
"openapi": "3.0.4",
"info": {
"title": "API SERP Bright Data",
"version": "1.0.0",
"description": "Extrayez les résultats des moteurs de recherche à l'aide de l'API SERP Bright Data. Extrayez des données structurées des principaux moteurs de recherche, notamment Google, Bing, Yandex, DuckDuckGo, etc. nObtenez des résultats organiques, des publicités payantes, des listes locales, des résultats d'achat et d'autres fonctionnalités SERP.n[Documentation de l'API SERP](https://docs.brightdata.com/scraping-automation/serp-api/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
],
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "SERP",
"description": "Opérations liées à l'API SERP de Bright Data."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
« paths » : {
« /request » : {
« post » : {
« operationId » : « sendSerpRequest »,
« summary » : « Envoyer une requête API SERP »,
« description » : « Soumettre une requête API SERP à l'aide de votre zone API SERP Bright Data. nn[Documentation API SERP `/request`](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)n",
"tags": [
"SERP"
],
"security": [
{
"BearerAuth": []
}
],
« requestBody » : {
« required » : true,
« content » : {
« application/json » : {
« schema » : {
« type » : « object »,
« required » : [
« Zone »,
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "Le nom de votre zone API SERP."
},
"url": {
"type": "string",
"description": "L'URL du moteur de recherche à interroger (par exemple, `https://www.google.com/search?q=<search_query>`).",
« example » : « https://www.google.com/search?q=pizza&hl=en&gl=us »
},
« format » : {
« type » : « string »,
« description » : « Format de réponse. nValeurs autorisées : n- `raw` : renvoie immédiatement la réponse dans le corps. n- `json` : renvoie la réponse sous forme d'objet JSON structuré. n",
"default": "raw",
"enum": [
"raw",
"json"
]
},
"country": {
"type": "string",
"description": "Code pays pour l'emplacement du Proxy (format ISO 3166-1 alpha-2). n",
"example": "us"
},
"data_format" : {
"type" : "string",
"description" : "Format des données de sortie SERP. nValeurs autorisées : n- `json` : données JSON entièrement analysées avec des résultats SERP structurés, y compris des extraits organiques, payants, locaux, commerciaux et de fonctionnalités.n- `markdown` : contenu SERP converti en Markdown. n",
"enum": [
"json",
"markdown"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Réponse réussie contenant les résultats de recherche."
},
"400": {
"description": "Demande non valide (champs obligatoires manquants ou paramètres non valides)."
},
"401": {
"description": "Non autorisé (clé API Bright Data invalide ou manquante)."
}
}
}
}
}
}Test dans Swagger Editor
Pour tester cette spécification, collez-la dans l’éditeur Swagger en ligne :
Test des spécifications OpenAPI de Bright Data pour l’intégration d’outils dans Dify
Pour vérifier que les spécifications OpenAPI ci-dessus permettant de se connecter aux services Bright Data via l’API fonctionnent, nous allons les tester dans Dify.
Plus précisément, nous testerons la spécification OpenAPI de l’API SERP de Bright Data, mais vous pouvez facilement adapter cette section guidée à d’autres spécifications SERP de l’API Web Unlocker.
Dify est une plateforme de développement open source et low-code qui simplifie la création, le déploiement et la gestion d’applications basées sur l’IA. Parmi ses nombreuses fonctionnalités, elle vous permet de définir des outils personnalisés à l’aide des spécifications OpenAPI.
Cette fonctionnalité n’est pas propre à Dify. Au contraire, de nombreuses autres plateformes de création d’agents IA, en particulier les solutions low-code/no-code ou prêtes à l’emploi, prennent également en charge l’intégration d’outils via les spécifications OpenAPI.
Découvrez d’autres intégrations avec Bright Data via les spécifications OpenAPI dans les guides suivants :
- Intégrer l’API SERP de Bright Data dans un agent IA dans Microsoft Copilot Studio
- Intégrer l’API SERP de Bright Data dans un agent IA dans IBM watsonx
Maintenant, testons les spécifications OpenAPI de Bright Data dans Dify !
Prérequis
Pour suivre cette section du tutoriel, vous avez besoin :
- Un compte Bright Data avec une clé API et une zone API SERP configurée.
- Un compte Dify Cloud pour utiliser la version cloud, ou une instance Dify locale fonctionnant sur votre machine.
Suivez le guide officiel pour générer une clé API Bright Data. Conservez-la en lieu sûr, car nous en aurons besoin pour authentifier les appels de l’outil API SERP.
Ensuite, suivez les instructions de la documentation Bright Data pour configurer une zone API SERP dans votre compte:
À partir de maintenant, nous supposerons que votre zone API SERP s’appelle serp_api. Veillez à adapter le nom de la zone dans les exemples afin qu’il corresponde au nom de votre zone.
Étape n° 1 : créer un nouvel outil personnalisé
Connectez-vous à votre compte Dify Cloud ou lancez votre instance locale. Pour créer un nouvel outil personnalisé, commencez par sélectionner l’option « Outils » dans le menu supérieur :
Sur la page « Outils », accédez à l’onglet « Personnalisé » :
Dans l’onglet « Personnalisé », cliquez sur la carte « Créer un outil personnalisé » :
La fenêtre modale « Créer un outil personnalisé » suivante apparaîtra :
Parfait ! C’est ici que vous allez coller votre spécification OpenAPI de l’API SERP de Bright Data.
Étape n° 2 : définir l’outil API SERP à l’aide de la spécification OpenAPI
Dans la fenêtre modale « Créer un outil personnalisé », donnez un nom à l’outil, par exemple « API SERP ». Dans le champ « Schéma », collez la spécification YAML OpenAPI pour l’API SERP de Bright Data.
Vous devriez voir quelque chose comme ceci :
Notez que la section « Outils disponibles » est remplie automatiquement en fonction de la définition fournie dans la spécification OpenAPI.
Comme prévu précédemment, la plupart des plateformes vous demandent de définir l’authentification via une méthode intégrée. Dans ce cas, pour ce faire, cliquez sur l’icône en forme d’engrenage dans la section « Authentication Method » (Méthode d’authentification) :
Configurez l’authentification comme suit :
- Type d’authentification: « En-tête »
- Type: « Bearer »
- Clé: « Authorization »
- Valeur: collez votre clé API Bright Data
Cela configure l’authentification via un en-tête d'autorisation, qui sera envoyé sous la forme :
Bearer <VOTRE_CLÉ_API_BRIGHT_DATA>Il s’agit précisément de la méthode d’authentification prise en charge par les API Bright Data.
Parfait ! L’outil API SERP est désormais défini et configuré correctement.
Étape n° 3 : tester l’outil
Dans la section « Outils disponibles », localisez la ligne correspondant au point de terminaison /request configuré et cliquez sur le bouton « Tester » :
Cela ouvrira la fenêtre modale « Test sendSerpRequest », dans laquelle vous pouvez personnaliser les paramètres et les valeurs afin de vérifier que l’outil configuré fonctionne.
Commencez par exemple par tester une réponse de base au format JSON. Le résultat attendu est une réponse JSON structurée contenant la page SERP extraite de Google au format HTML (format de données par défaut de l’API SERP) :
Faites défiler vers le bas jusqu’à la section « Résultats du test » pour afficher la réponse de l’API. Vous verrez que le champ body dans le JSON contient le HTML de la page SERP comme prévu :
Fantastique ! Ce résultat correspond aux attentes.
Essayez maintenant d’obtenir la version Markdown de la même page directement dans le corps de la réponse :
Remarquez que cette fois-ci, la réponse est du texte brut (car format : raw) contenant les données SERP au format Markdown (en raison de data_format : markdown),prêtes à être ingérées par LLM.
Maintenant que vous savez que l’outil fonctionne (car il appelle avec succès l’API sous-jacente), vous pouvez l’intégrer à n’importe quel workflow Dify ou agent IA.
Et voilà ! L’outil Bright Data défini via la spécification OpenAPI fonctionne parfaitement.
Conclusion
Dans cet article, vous avez appris pourquoi les plateformes et bibliothèques d’IA vous permettent d’utiliser les spécifications OpenAPI pour la définition d’outils et comment Bright Data prend en charge cette option. Vous avez notamment découvert les spécifications OpenAPI pour les solutions Web Unlocker et API SERP de Bright Data.
En intégrant ces deux outils, vous pouvez créer des agents IA complexes qui effectuent des recherches sur le Web et récupèrent des données Web pour le RAG, la recherche approfondie et de nombreuses autres tâches. Tirez parti de la suite complète des services API Bright Data pour l’IA afin de libérer tout le potentiel de vos agents !
Créez gratuitement un compte Bright Data dès aujourd’hui et commencez à intégrer nos API pour la récupération de données web !
