このブログ記事では以下の内容をご覧いただけます：
- OpenAPI仕様とは何か。
- AIフレームワークやプラットフォームにおけるツール定義で広く採用される理由
- Bright DataがAIエージェントやワークフローへの統合を簡素化するためにOpenAPIをどのようにサポートしているか。
- Bright Data Web Unlocker APIのOpenAPI仕様。
- Bright Data SERP APIのOpenAPI仕様
- これらの仕様が実際のAIプラットフォーム内でどのように機能するか
さあ、詳しく見ていきましょう！
OpenAPI仕様とは？
OpenAPI仕様（OAS）は、RESTful APIを記述するための言語非依存のオープンスタンダードです。APIの操作、パラメータ、レスポンス、セキュリティスキーム、その他の特性を定義するための構造化された機械可読形式（通常はYAMLまたはJSON）を提供します。
仕様の GitHub リポジトリをご覧ください！
注：OpenAPI仕様は当初「Swagger仕様」と呼ばれていました。したがって、「Bright Data Swagger仕様」をお探しの方は、ここが正しい場所です！
多くのAIソリューションがツール定義にOpenAPI仕様を採用する理由
多くのAIフレームワークがツール定義にOpenAPIサポートを採用しています。主な理由は、OpenAPI仕様が外部APIの機能を正確に記述する標準化された機械可読契約を提供するためです。
この標準化により、主に3つの利点が生まれます：
- 相互運用性と摩擦の最小化：OpenAPIは広くサポートされている標準です。仕様を提供すれば、プラットフォームはAPIを自動インポートし、入力フォーム、呼び出し、応答処理を生成し、ツールに統合できます。
- 学習曲線の低減：非技術ユーザーでも、ドキュメントや他のソースからOpenAPI仕様をコピーするだけでAPIを使用したツールを構築できます。手動での配線やコーディングが不要なため、ローコード/ノーコードAIプラットフォームでOpenAPIサポートが広く普及している理由です。
- メンテナンス性の向上：明示的なAPI契約により更新が容易です。APIが進化しても、ツール定義内の仕様を更新するだけで済み、メンテナンスが大幅に簡素化され大規模な書き換えの必要性が低減します。
要するに、OpenAPIによるツール定義は、CRM、データプロバイダー、内部API、その他の外部サービスを安全に接続・文書化・維持できるエンタープライズ対応エコシステムへの扉を開きます。AIエージェント、パイプライン、ワークフローにおいて、最小限の手動オーバーヘッドで運用可能です。
Bright DataのOpenAPI仕様のご紹介
Bright Dataは、ウェブデータ抽出、自動化されたウェブ操作、ウェブクローリングなど、幅広い製品とサービスを提供しています。
これらのソリューションはAPI（およびノーコードオプション）経由で利用可能であり、この機能をサポートするAIプラットフォームではOpenAPI仕様を使用して設定できます。
本記事では、Bright Dataの最も重要なツール2つに焦点を当てます：
- SERP API：Google、Bing、Yandexなどの検索エンジンから構造化データを自動抽出。プロキシ管理、CAPTCHAの解決、JavaScriptレンダリングといった複雑な処理を処理し、ブロックされることなくクリーンなリアルタイム結果をJSONまたはHTML形式で取得可能。
- Web Unlocker API：複雑なボット対策（CAPTCHA、IPブロック、フィンガープリンティングなど）を回避し、あらゆるウェブページからデータを抽出します。プロキシ管理、実ユーザーエミュレーションを仲介し、クリーンなHTML、JSON、Markdown形式のレスポンスを提供します。
各サービスには、YAML形式とJSON形式の両方でOpenAPI 3.x仕様が用意されており、Swagger Editorでのテスト例も確認できます。
これらの仕様を起点に、ウェブスクレイピングAPIやその他のAPIエンドポイントを同様にOpenAPI仕様に変換し、AI統合に活用できます。
注記: 一部のBright Data製品は同一のAPIエンドポイントを共有し、リクエストボディのみに基づいて動作を変更します。同一のパスとメソッドに対して完全に独立した2つの仕様を単一のOpenAPIドキュメントで定義できないため、別々のOpenAPI仕様が必要です。そのため、SERP APIとWeb Unlocker API（同一エンドポイントを共有）にはそれぞれ専用のOpenAPI仕様を提供します。
Web Unlocker API OpenAPI仕様
Bright DataのWeb Unlocker API向けOpenAPI仕様をご覧ください。
注記: 詳細については、以下のドキュメントページで利用可能な引数、オプション、認証方法などを確認してください:
YAML仕様
以下は Bright Data Web Unlocker API の OpenAPI YAML 仕様です：
openapi: 3.0.4
info:
title: Bright Data Web Unlocker API
version: 1.0.0
description: |
Bright Data Web Unlocker APIは、アンチボット対策の回避、プロキシ管理、CAPTCHAの自動解決を可能にし、ウェブデータ収集を容易にします。
[Web Unlocker API ドキュメント](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: Web Unlocker
description: Bright Data Web Unlocker API との連携操作。
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: BRIGHT_DATA_API_KEY
paths:
/request:
post:
operationId: sendWebUnlockerRequest
summary: Web Unlocker API リクエストを送信
description: |
Bright Data Web Unlocker API ゾーンを使用して Web Unlocker API リクエストを送信します。
[Web Unlocker API `/request` ドキュメント](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)
tags:
- Web Unlocker
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- zone
- url
- format
properties:
zone:
type: string
description: あなたのWeb Unlockerゾーン名。
url:
type: string
description: アンロックして取得する対象ウェブサイトのURL。
example: https://example.com/products
format:
type: string
description: |
レスポンス形式。
許可値:
- `raw`: レスポンスをボディに即時返却。
- `json`: 構造化されたJSONオブジェクトとしてレスポンスを返却。
default: raw
method:
type: string
description: 対象URLを取得する際に使用するHTTPメソッド。
example: GET
country:
type: string
description: |
プロキシ位置の国コード（ISO 3166-1 alpha-2形式）。
example: us
data_format:
type: string
description: |
スクレイピング出力データのフォーマット。
許可値:
- `markdown`: ページコンテンツをMarkdownに変換。
- `screenshot`: レンダリング済みページのPNG画像をキャプチャ。
enum:
- markdown
- screenshot
responses:
"200":
description: 検索結果を含む正常なレスポンス。
"400":
description: 無効なリクエスト（必須フィールドの欠落または無効なパラメータ）。
"401":
description: 認証不足（無効または欠落したBright Data APIキー）。注記:securitySchemesセクションは、HTTPベアラ認証を使用するセキュリティスキームを指定します。具体的には、クライアントはAPI呼び出し時にAuthorizationヘッダーにBRIGHT_DATA_API_KEYをベアラトークンとして送信する必要があります。
一方で、ほとんどのAIプラットフォームには既に認証方法が組み込まれており、この指定フィールドを無視する場合があります。ただし、明確化と参照のため、OpenAPI仕様に含めることは有用です。
JSON仕様
以下は Web Unlocker API の JSON OpenAPI 仕様です：
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data Web Unlocker API",
"version": "1.0.0",
"description": "Bright Data Web Unlocker APIは、アンチボット対策の回避、プロキシ管理、CAPTCHAの自動解決を可能にし、ウェブデータ収集を容易にします。\n[Web Unlocker API ドキュメント](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": "Bright Data Web Unlocker APIとの連携操作を提供します。"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendWebUnlockerRequest",
"summary": "Web Unlocker API リクエストを送信",
"description": "Bright Data Web Unlocker API ゾーンを使用して Web Unlocker API リクエストを送信します。 nn[Web Unlocker API `/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": [
"ゾーン",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "Web Unlockerのゾーン名です。",
},
"url": {
"type": "string",
"description": "アンロックして取得する対象ウェブサイトのURL。",
"example": "https://example.com/products"
},
"format": {
"type": "string",
"description": "レスポンス形式。 n許可値: n- `raw`: レスポンスをボディに即時返却。 n- `json`: 構造化されたJSONオブジェクトとしてレスポンスを返します。 n",
"default": "raw"
},
"method": {
"type": "string",
"description": "対象URLを取得する際に使用するHTTPメソッド。",
"example": "GET"
},
"country": {
"type": "string",
"description": "プロキシ位置の国コード（ISO 3166-1 alpha-2 形式）。n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "スクレイピングされた出力データの形式。 n許可値:n- `markdown`: ページコンテンツをMarkdown形式に変換n- `screenshot`: レンダリングされたページのPNG画像をキャプチャn",
"enum": [
"markdown",
"screenshot"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "検索結果を含む正常なレスポンス。"
},
"400": {
"description": "無効なリクエスト（必須フィールドの欠落または無効なパラメータ）。"
},
"401": {
"description": "未認証（無効または欠落しているBright Data APIキー）"
}
}
}
}
}
}Swagger Editorでのテスト
OpenAPI仕様をSwagger Editorに貼り付けてテストします:
SERP API OpenAPI仕様
Bright DataのSERP API向けOpenAPI仕様を探索してください。
注: 詳細については、以下のドキュメントページで引数、オプション、認証方法などを参照してください:
YAML仕様
以下は SERP API の OpenAPI YAML 仕様です：
openapi: 3.0.4
info:
title: Bright Data SERP API
version: 1.0.0
description: |
Bright Data SERP APIを使用して検索エンジン結果を抽出します。Google、Bing、Yandex、DuckDuckGoなどの主要検索エンジンから構造化データを抽出します。
オーガニック検索結果、有料広告、ローカルリスティング、ショッピング結果、その他のSERP機能を取得します。
[SERP API ドキュメント](https://docs.brightdata.com/scraping-automation/serp-api/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: SERP
description: Bright Data SERP API に関連する操作。
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: BRIGHT_DATA_API_KEY
paths:
/request:
post:
operationId: sendSerpRequest
summary: SERP APIリクエストを送信
description: |
Bright Data SERP API ゾーンを使用して SERP API リクエストを送信します。
[SERP API `/request` ドキュメント](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)
tags:
- SERP
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- zone
- url
- format
properties:
zone:
type: string
description: SERP API ゾーンの名前。
url:
type: string
description: クエリ対象の検索エンジンURL（例: `https://www.google.com/search?q=<search_query>`）。
example: https://www.google.com/search?q=pizza&hl=en&gl=us
format:
type: string
description: |
レスポンス形式。
許可値:
- `raw`: レスポンスをボディに直接返します。
- `json`: 構造化されたJSONオブジェクトとしてレスポンスを返します。
デフォルト: raw
列挙型:
- raw
- json
country:
type: string
description: |
プロキシ位置の国コード（ISO 3166-1 alpha-2 形式）。
example: us
data_format:
type: string
description: |
SERP出力データの形式。
許可値:
- `json`: オーガニック、有料、ローカル、ショッピング、フィーチャースニペットを含む構造化されたSERP結果の完全パース済みJSONデータ。
- `markdown`: Markdownに変換されたSERPコンテンツ。
enum:
- json
- markdown
responses:
"200":
description: 検索結果を含む正常なレスポンス。
"400":
description: 無効なリクエスト（必須フィールドの欠落または無効なパラメータ）。
"401":
description: 認証失敗（無効または欠落したBright Data APIキー）。JSON仕様
これは SERP API の JSON OpenAPI 仕様です:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data SERP API",
"version": "1.0.0",
"description": "Bright Data SERP APIを使用して検索エンジンの結果を抽出します。 Google、Bing、Yandex、DuckDuckGoなどの主要検索エンジンから構造化データを抽出します。 nオーガニック検索結果、有料広告、ローカルリスティング、ショッピング結果、その他のSERP機能を取得できます。n[SERP APIドキュメント](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": "Bright Data SERP APIに関連する操作。"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendSerpRequest",
"summary": "SERP APIリクエストを送信",
"description": "Bright Data SERP APIゾーンを使用してSERP APIリクエストを送信します。 nn[SERP API `/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": [
"ゾーン",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "SERP API ゾーンの名前。
},
"url": {
"type": "string",
"description": "クエリを送信する検索エンジンのURL（例: `https://www.google.com/search?q=<search_query>`）",
"example": "https://www.google.com/search?q=pizza&hl=en&gl=us"
},
"format": {
"type": "string",
"description": "レスポンス形式。 n許可値: n- `raw`: レスポンスをボディに直接返す。 n- `json`: 構造化されたJSONオブジェクトとしてレスポンスを返す。 n",
"default": "raw",
"enum": [
"raw",
"json"
]
},
"country": {
"type": "string",
"description": "プロキシ位置の国コード（ISO 3166-1 alpha-2 形式）。n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "SERP出力データのフォーマット。 n許可値:n- `json`: オーガニック、有料、ローカル、ショッピング、フィーチャースニペットを含む構造化されたSERP結果の完全パース済みJSONデータ。n- `markdown`: Markdownに変換されたSERPコンテンツ。 n",
"enum": [
"json",
"markdown"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "検索結果を含む正常なレスポンス。"
},
"400": {
"description": "無効なリクエスト（必須フィールドの欠落または無効なパラメータ）"
},
"401": {
"description": "未認証（無効または欠落したBright Data APIキー）"
}
}
}
}
}
}Swagger Editorでのテスト
この仕様をテストするには、オンラインSwagger Editorに貼り付けてください：
Difyにおけるツール統合のためのBright Data OpenAPI仕様のテスト
API経由でBright Dataサービスに接続するための上記のOpenAPI仕様が機能することを確認するため、Difyでテストします。
具体的には、Bright Data SERP API OpenAPI仕様をテストしますが、このガイドセクションは他のWeb Unlocker API SERP仕様にも簡単に適応できます。
Difyはオープンソースのローコード開発プラットフォームであり、AI搭載アプリケーションの構築・デプロイ・管理を簡素化します。その数多くの機能の中でも、OpenAPI仕様を用いたカスタムツールの定義が可能です。
この機能はDify固有のものではありません。むしろ、他の多くのAIエージェント構築プラットフォーム、特にローコード/ノーコードやエンタープライズ対応ソリューションも、OpenAPI仕様を介したツール統合をサポートしています。
以下のガイドで、OpenAPI仕様を介したBright Dataとの追加統合方法をご覧ください：
- Microsoft Copilot StudioのAIエージェントにBright DataのSERP APIを統合する
- IBM watsonxのAIエージェントにBright DataのSERP APIを統合する
それでは、DifyでBright DataのOpenAPI仕様をテストしてみましょう！
前提条件
このチュートリアルセクションを実行するには、以下が必要です：
- APIキーとSERP APIゾーンが設定されたBright Dataアカウント
- クラウド版を使用する場合はDify Cloudアカウント、またはローカルマシン上で動作するDifyインスタンス。
公式ガイドに従ってBright Data APIキーを生成してください。このキーはSERP APIツールの呼び出し認証に必要となるため、安全な場所に保管してください。
次に、Bright Dataのドキュメントに記載されている手順に従い、アカウント内でSERP APIゾーンを設定してください:
以降、SERP APIゾーン名を「serp_api」と仮定します。例示されるゾーン名は、ご自身のゾーン名に合わせて変更してください。
ステップ #1: 新しいカスタムツールを作成する
Dify Cloudアカウントにログインするか、ローカルインスタンスを起動します。新しいカスタムツールを作成するには、まず上部メニューの「ツール」オプションを選択します：
「ツール」ページで「カスタム」タブに移動します：
「カスタム」タブで「カスタムツールを作成」カードをクリックします：
以下の「カスタムツールを作成」モーダルが表示されます：
これで準備完了です。ここにBright Data SERP APIのOpenAPI仕様を貼り付けます。
ステップ #2: OpenAPI仕様を使用してSERP APIツールを定義する
「カスタムツールを作成」モーダルで、ツールに「SERP API」などの名前を付けます。「スキーマ」フィールドに、Bright Data SERP APIのYAML OpenAPI仕様を貼り付けます。
以下のような画面が表示されます：
OpenAPI仕様で定義された内容に基づき、「利用可能なツール」セクションが自動的に生成される点にご注意ください。
前述の通り、ほとんどのプラットフォームでは組み込みメソッドによる認証定義が必要です。本ケースでは「認証方法」セクションの歯車アイコンをクリックして設定します：
認証を以下のように設定します：
- 認証タイプ: 「ヘッダー」
- タイプ: 「Bearer」
- キー: 「Authorization」
- 値：Bright Data APIキーを貼り付け
これにより、Authorizationヘッダーを介した認証が設定されます。送信されるヘッダーは次の形式になります:
Bearer <YOUR_BRIGHT_DATA_API_KEY>これはBright Data APIがサポートする認証方法そのものです。
素晴らしい！SERP APIツールが正しく定義・設定されました。
ステップ #3: ツールのテスト
「利用可能なツール」セクションで、設定済みの/requestエンドポイントの行を見つけ、「テスト」ボタンをクリックします:
これにより「Test sendSerpRequest」モーダルが開き、パラメータと値をカスタマイズして設定したツールが動作することを確認できます。
例えば、まずJSON形式での基本レスポンスをテストしてみましょう。期待される結果は、GoogleからスクレイピングされたSERPページをHTML形式で含む構造化されたJSONレスポンスです（SERP APIのデフォルトデータ形式）。
「テスト結果」セクションまでスクロールしてAPIレスポンスを確認します。JSONのbodyフィールドに期待通りSERPページのHTMLが含まれていることが確認できます：
素晴らしい！この結果は期待通りです。
次に、同じページのMarkdown版をレスポンス本文で直接取得してみましょう：
今回は、format: raw によりプレーンテキストで返され、data_format: markdown によりSERPデータがMarkdown形式で含まれている点に注目してください。これによりLLMへの取り込みが容易になります。
ツールが機能していることが確認できたので（基盤となるAPIを正常に呼び出せているため）、これを任意のDifyワークフローやAIエージェントに統合できます。
これで完了！OpenAPI仕様で定義されたBright Dataツールは完璧に動作します。
結論
本記事では、AIプラットフォームやライブラリがツール定義にOpenAPI仕様を採用する理由と、Bright Dataがこのオプションをどのようにサポートしているかを学びました。特に、Bright DataのWeb UnlockerおよびSERP APIソリューションのOpenAPI仕様を確認しました。
これら2つのツールを統合することで、ウェブ検索やRAG（Retrieval-Augmented Generation）、深い調査など、様々なタスクのためのAIのためのデータを取得する複雑なAIエージェントを作成できます。Bright DataのAI向けAPIサービス一式を活用し、エージェントの真の潜在能力を解き放ちましょう！
今すぐBright Dataアカウントを無料で作成し、ウェブデータ取得のためのAPI統合を始めましょう！
