アレクサスクレイパーAPIガイド：回答、引用、製品を抽出する

TL;DR:

• Alexa Scraperは、プロンプトを構造化された回答データに変換します。 scraper.alexaアクターは、参照、ソース、提案、条件付き製品記録と共にMarkdownおよびプレーンテキストの回答を返します。
• リクエストには2つの必須アクター入力があります。 自然言語のpromptとcountryコードをAlexaアクターに送信します。
• 現在の文書化されたエンドポイントは/api/v2/scraper/requestです。 x-api-tokenヘッダーで認証し、HTTP POST経由でJSONを送信します。
• 製品フィールドは設計上nullableです。 Alexaの回答が製品コンテキストを持たない場合、products配列は空であることがあります。
• 参照とソースは回答に添付されるべきです。 これらの子レコードをキャプチャと共に保持することで、下流のブランド、GEO、および製品の分析の背後にある証拠が保存されます。
• 無料で始められます。 新しいScrapelessアカウントは、app.scrapeless.comで無料プランへのアクセスを含みます。

はじめに: Alexaの回答には安定したデータインターフェースが必要

Alexaの回答には、1つの文以上のものが含まれています。Markdown、プレーンテキスト、参照、ソースリンク、推奨されるフォローアップ質問、会話識別子、処理指令、および製品記録を含むことができます。表示される回答をコピーすると、その構造の多くが失われます。

Scrapeless Alexa Scraperは、scraper.alexaアクターを通じて応答を公開します。クライアントはプロンプトと国を送信し、アクターは音声アシスタントインターフェースを解析せずに保存できるフィールドを返します。同じリクエスト形状が、GEO監視、回答品質レビュー、ソース分析、および製品の可視性作業に役立ちます。

このガイドでは、現在のAlexa Scraperドキュメントを使用しています。エンドポイント、認証、リクエストパラメータ、応答フィールド、cURLリクエスト、Pythonクライアント、および構造化出力のストレージパターンについて説明しています。

Alexa Scraperでできること

Alexa Scraperは、回答とその周辺の証拠を1つの記録で必要とするワークフローをサポートします。

• 回答テキストをキャプチャします。 レンダリングされたコンテンツに対してmd_textを保存し、プレーンテキスト処理に対してraw_textを保存します。
• 引用を確認します。 referencesから参照ID、タイトル、およびURLを読み取ります。
• ソースリンクをマッピングします。 sourcesからソース表示テキスト、URL、タイプ、およびフラグメントURIを保存します。
• フォローアッププロンプトを発見します。 suggestionsにAlexaが表示するテキストとメッセージ値を収集します。
• 応答コンテキストを追跡します。 完了状態、回答の修正、ダイアログリクエストID、エンドポイントID、フラグメント数、および会話IDを保持します。
• 製品の浮上を分析します。 製品データが適用される場合、製品識別子、引用リンク、タイトル、画像、URL、価格、配送テキスト、詳細、および目的を読み取ります。

アクターはキャプチャデータを返します。メンション率、ソース濃度、回答の一貫性、製品の出現率などのメトリクスは、データを使用するチームによって定義された下流の計算です。

なぜScrapeless Alexa Scraperなのか

Scrapeless Alexa Scraperは、マーケット全体でAlexaの応答をキャプチャするための文書化されたアクターインターフェースを提供します。

実装の価値は応答形状から来ます：

• 回答テキストはMarkdownおよびプレーンテキスト形式で到着します。
• 引用とソースリンクは、文章に埋め込まれたリンクではなく、別々の配列です。
• 提案されたプロンプトは構造化されたレコードとして返されます。
• 製品情報は条件付き配列として利用可能です。
• 国は市場特有のキャプチャのための明示的なリクエスト入力です。
• 会話および回答識別子は、トレーサビリティのために保持できます。

Scrapeless LLMチャットスクレイパーは、Universal Scraping APIラインの一部です。Universal Scraping API製品ページが製品のホームであり、現在のプランの詳細はScrapeless料金ページに記載されています。

前提条件

必要なもの：

• Scrapelessアカウントとapp.scrapeless.comから取得したAPIキー
• シェル例のためのcURL
• PythonとPython例のためのrequestsパッケージ
• キャプチャしたい市場のサポートされている国コード

country入力は短い国コードを使用します。 ISO 3166国コード標準は一般的なアルファ2形式を説明しています。特定のコードの製品の可用性を確認するには、Scrapelessのサポート国リストを使用してください。

注記: 以下の認証されたリクエストは、実際のScrapeless APIキーとアクセス可能なWebhookを必要とします。これらの資格情報が無ければ、ブロックは構文チェックが可能ですが、ライブのAlexa結果を生成することはできません。

AlexaスクレイパーAPIの仕組み

Alexaスクレイパーリクエストは、アクターの名前を指定し、プロンプトと国を提供し、Webhook宛先を指定するHTTP POSTです。

現在文書化されているエンドポイントは以下の通りです。

https://api.scrapeless.com/api/v2/scraper/request

HTTPは、HTTPセマンティクス標準を通じてリクエストメソッドとヘッダーフィールドを定義します。このリクエストでは、Content-Type: application/json がボディ形式を記述し、x-api-token がScrapeless APIキーを運びます。

そのAPIキーは、ソースコードではなく、秘密のストアまたは保護された環境変数に保管してください。OWASP秘密管理のガイダンスでは、ストレージ、ローテーション、およびアクセスに関する実用的な管理策が示されています。

リクエストパラメーター

プロンプトと国は、返された回答と同じデータベースレコードに保管してください。この2つの入力が観測を定義し、後の比較を再現可能にします。

cURLによるクイックキャプチャ

リクエストを実行する前に、シェル内でSCRAPELESS_API_KEYおよびSCRAPELESS_WEBHOOK_URLを設定してください。

注記: このブロックは資格情報が必要なリクエストです。実際のScrapeless APIキーと公開Webhook URLが必要です。

curl 'https://api.scrapeless.com/api/v2/scraper/request' \
  --header 'Content-Type: application/json' \
  --header "x-api-token: ${SCRAPELESS_API_KEY}" \
  --data-binary @- <<JSON
{
  "actor": "scraper.alexa",
  "input": {
    "prompt": "ニューヨークのおすすめの観光地",
    "country": "US"
  },
  "webhook": {
    "url": "${SCRAPELESS_WEBHOOK_URL}"
  }
}
JSON

ペイロードはJSONであり、相互運用可能な文法はRFC 8259によって定義されています。文字列の値は引用符で囲み、提出されたボディ内のコメントは避けてください。

応答フィールド

アクター結果は、答えの内容、識別子、指示、参照、ソース、提案、製品のフィールドをグループ化します。

以下のJSONは、文書化されたフィールドリストから構築された説明的な形です。値は例示であり、キャプチャされたアクターの実行ではありません。

{
  "user_text": "小さなキッチンに適したコーヒーメーカーはどれですか？",
  "md_text": "コンパクトなコーヒーメーカーは、フットプリントと容量のバランスを取るべきです。",
  "raw_text": "コンパクトなコーヒーメーカーは、フットプリントと容量のバランスを取るべきです。",
  "completed": true,
  "answer_revision": 1,
  "conversation": {
    "id": "illustrative-conversation-id"
  },
  "references": [
    {
      "id": "cite_example",
      "title": "説明的な購入ガイド",
      "url": "https://example.com/illustrative-buying-guide"
    }
  ],
  "sources": [
    {
      "text": "説明的なソース",
      "url": "https://example.com/illustrative-buying-guide",
      "type": "OpenURL",
      "fragment_uri": "illustrative-source-fragment"
    }
  ],
  "suggestions": [
    {
      "text": "コンパクトモデルを比較",
      "message": "コンパクトなコーヒーメーカーを比較",
      "type": "TextMessage",
      "fragment_uri": "illustrative-suggestion-fragment"
    }
  ],
  "products": []
}

空の製品配列は意図的です。製品情報は条件付きであるため、パーサーは空のリストを受け入れる必要があります。

無料プランでAPIキーを取得してください: app.scrapeless.com

PythonでのAlexaスクレイパー統合

Pythonクライアントは、文書化されたリクエストを送信し、リクエストワークフローの応答を印刷することができます。最終的なAlexaアクター結果は、構成されたワークフローを通じて配信され、リクエストの後に示された正規化関数に渡される必要があります。
唯一のサードパーティ依存関係をインストールします。このセットアップステップでは、Pythonパッケージインデックスへのアクセスが必要です。

python -m pip install requests

注意: 以下のリクエストブロックは資格情報で保護された例です。SCRAPELESS_API_KEYおよびSCRAPELESS_WEBHOOK_URL環境変数が必要です。

import os
import requests

API_URL = "https://api.scrapeless.com/api/v2/scraper/request"

api_key = os.environ["SCRAPELESS_API_KEY"]
webhook_url = os.environ["SCRAPELESS_WEBHOOK_URL"]

payload = {
    "actor": "scraper.alexa",
    "input": {
        "prompt": "ニューヨークのおすすめ観光地",
        "country": "US",
    },
    "webhook": {
        "url": webhook_url,
    },
}

response = requests.post(
    API_URL,
    headers={
        "Content-Type": "application/json",
        "x-api-token": api_key,
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

APIキーを環境変数に保存してください。ソース管理、ノートブック、スクリーンショット、またはキャプチャされたWebhookペイロードに配置しないでください。

Alexaの出力をストレージ用に正規化する

正規化されたAlexaレコードは、親レベルで回答を保持し、繰り返される配列を子レコードとして保存します。

以下の情報を持つ親capturesテーブルを使用してください：

• 内部キャプチャID
• 提出されたプロンプト
• 提出された国
• user_text、md_text、およびraw_text
• completedおよびanswer_revision
• 会話およびダイアログ識別子
• システムによって生成されたキャプチャのタイムスタンプ

references、sources、suggestions、directives、およびproductsをキャプチャIDにキー付けされた別のテーブルに保存します。これにより、すべてのソースや製品に対してフルアンサーを重複させることを避けます。

ソース関係は明示的でクエリ可能であるべきです。アクターはすでに、それらの関係を引用ID、ソースURL、およびフラグメントURIを通じて公開しています。彼らを平坦化して非構造化テキストフィールドに変換するのではなく、保持してください。

製品行については、citation_idがnullの場合でも保持してください。存在する場合、製品を文書化された参照に関連づけることができます。存在しない場合、null値はそのフィールドで直接引用リンクが返されなかったことを正確に記録します。

一般的な統合問題を避ける方法

Alexa Scraperの統合は、nullableフィールド、国のスコープ、および応答証拠が明示的に扱われると予測可能な状態を保ちます。

条件付き配列を空のコレクションとして扱う

products配列は、製品情報が該当しない場合は空であることがあります。同様の防御パターンがreferences、sources、suggestions、およびdirectivesにも役立ちます：変換レイヤーで欠落またはnullの配列を空のコレクションとして読み込み、監査のために元のペイロードを保持します。

マークダウンとプレーンテキストを保持する

md_textとraw_textは異なる目的をサポートします。マークダウンは可視構造を表示および保持するのに便利です。プレーンテキストはトークン化、比較、検索が簡単です。両方を保存することで、後のパイプラインが一方の形式から他方を再構築するのを防ぎます。

すべてのレコードで国を固定する

ダウンストリームストレージにおいてデフォルト市場に依存しないでください。プロンプトや結果の横に、正確な提出国を保存します。キャプチャがリクエストコンテキストに結びつけられない場合、市場比較は失敗します。

ドメインでグループ化する前に引用IDを保持する

ドメインレベルのレポートは便利ですが、元の参照およびソースレコードから導出されるべきです。正規化されたドメインフィールドを追加する前に、引用ID、タイトル、完全URL、ソースタイプ、フラグメントURIを保持してください。

アクターの出力と導出スコアを分離する

アクターは回答とコンテキストフィールドを返します。メンション率、引用率、ソースの多様性、主張の正確さ、製品の出現はキャプチャ後に作成される分析です。導出スコアは別のテーブルまたはネームスペースに保存し、レビュアーがAPI出力とチームの解釈を区別できるようにします。

回答エンジンデータのための補足読書

Alexa Scraperは1つのLLM回答サーフェスをカバーします。Google AI Overview Scraper APIガイドは、独自のフィールドモデルを持つ検索主導の回答体験のための関連するアクターパターンを示しています。

アクター間で真に一致するフィールド（提出されたプロンプト、国、回答テキスト、ソースURL、キャプチャID、キャプチャ時間）についてのみ共有ストレージ契約を利用してください。製品フラグメント、提案メッセージ、プラットフォーム識別子が最低共通母体スキーマに消えないように、それぞれのアクター専用のフィールドは自分のテーブルに保持してください。

結論: 回答とその証拠を保持する

Alexa Scraper統合は、小さなリクエストサーフェス（アクター、プロンプト、国、認証ヘッダー、およびWebhookワークフロー）を持っています。応答モデルは、回答、参照、ソース、提案、指示、会話コンテキスト、条件付き製品を保持するために広がっています。
生のペイロードと正規化された親キャプチャを保存することから始めます。繰り返しのレコード用の子テーブルを追加し、 nullable な製品フィールドを保持し、派生分析はアクターの出力とは別に保ちます。その構造は、コレクションレイヤーを再構築することなく、将来のブランド、GEO、製品、マーケットのユースケースをサポートします。

Alexa Scraperで構築する準備はできましたか？

コミュニティに参加して無料プランを獲得し、LLM回答データパイプラインを構築している開発者とつながりましょう: Discord · Telegram。

app.scrapeless.com にサインアップして、1つのプロンプト、1つのサポート国、およびあなたが制御できるWebhookエンドポイントでアクターをテストしてください。

よくある質問

Q: Alexa Scraperはどのエンドポイントを使用しますか？

Alexa Scraperは現在のアクタードキュメントでPOST https://api.scrapeless.com/api/v2/scraper/requestを使用します。このリクエストはscraper.alexaをアクター値として使用します。

Q: Alexa Scraperに必要な入力は何ですか？

アクターはinputオブジェクト内にプロンプトと国コードを必要とします。文書化されたリクエスト例には、リクエストワークフローのためのWebhook URLも含まれています。

Q: md_textとraw_textの違いは何ですか？

md_textはMarkdown形式のAlexaの回答で、raw_textはプレーンテキストの回答です。パイプラインが忠実なレンダリングとテキスト分析を必要とする場合は、両方を保存してください。

Q: Alexa Scraperは常に引用を返しますか？

Alexa Scraperはreferencesとsourcesの配列を公開しますが、下流のコードはこれらの配列が空であることを許可する必要があります。引用の存在は、返された回答に依存します。

Q: Alexa Scraperは常に製品を返しますか？

いいえ。製品情報は条件付きであり、適用されない場合はproducts配列が空である可能性があります。

Q: PythonなしでAlexa Scraperを使用できますか？

はい。認証されたJSON POSTを送信し、リクエストワークフローのレスポンスを受信できるクライアントであれば、アクターを使用できます。cURLの例は直接統合テストに十分です。

Q: APIキーはどのように保存すべきですか？

Scrapeless APIキーは環境変数または管理されたシークレットストアに保存してください。キーをソースコントロールにコミットしたり、Webhookログに含めたりしないでください。