Response Headers

FourA APIからのすべてのレスポンスには、少数のカスタムヘッダーが含まれています。これらは、トレース、サポート、請求の照合、事後分析に役立ちます。

FourAが設定するヘッダー

ヘッダー	設定条件	説明
`X-Foura-Request-Id`	エラーや401を含む、すべての`/api/*`レスポンス	このリクエストを識別するUUID。ログに記録してください。
`X-FourA-Credits`	バックエンドに到達したすべての`/api/*`レスポンス	この呼び出しで消費されたクレジット。成功時と失敗時の両方で返されます(どちらの場合も処理は行われたため)。
`Content-Type`	すべてのレスポンス	エンベロープに対して常に`application/json`。ターゲットのcontent-typeは、エンベロープの`headers`フィールド内で返されます。

X-Foura-Request-Id

POST /api/auto/、POST /api/single/、POST /api/proxy/、POST /api/browser/への各呼び出しにはUUIDがタグ付けされます。このヘッダーは認証が失敗した場合でも設定されるため、設定ミスの呼び出しも関連付けることができます。

curl -i -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

HTTP/1.1 200 OK
X-Foura-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

使用するタイミング

サポートチケット: リクエストIDを含めていただくと、当社の記録から正確な呼び出しを見つけることができます。
独自のログ: アプリケーションのログ行の横に保存します。顧客から「14:32のデータが間違っていた」と苦情があった場合、正確なリクエストをリプレイできます。
ダッシュボードのトレース: 管理しているキーのActivity feedに同じIDが表示されるため、一致する行を開いて、キャプチャされたリクエストとレスポンスを検査できます。

例: お客様側でのログ記録

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-Foura-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()

async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-Foura-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

X-FourA-Creditsは、実行したばかりの呼び出しのクレジットコストを報告します。これは請求書ではなくメーターです。ヘッダーは結果に関係なく消費された作業量を反映します。ダッシュボードの請求レイヤーは、プランに対して請求可能な結果のみをカウントします(どの結果が請求可能かについては、Request Outcomesを参照してください)。

コスト参照

エンジン	ベース	`unblocker`あり
Single	1	2
Proxy	5	10
Browser	15	30 (防御が解決された場合)

/api/auto/は個別の請求可能な行を追加しません。そのクレジットコストは、内部で実行されたサブコールの合計です(ウォームターゲットでの1回のリプレイは2で終了する場合があります。ハードなサイトでのコールドな解決ははるかに多くを消費する可能性があります)。autoレスポンスのX-FourA-Credits値は、本文のmeta.creditsと等しく、ラダーのフルコストを追跡します。

なぜヘッダーと本文のフィールドの両方があるのか?

ヘッダーは便利です。本文を解析する前に読み取ったり、リクエスト行の横にログに記録したり、JSON解析なしで多数の呼び出しで合計したりできます。本文のmeta.credits (Auto)またはエンジンごとのメタデータ(Single、Proxy、Browserのダッシュボード)は同じ数値を保持しますが、レスポンスエンベロープ内で読み取り可能です。

キャッシュの動作

APIはレスポンスにCache-ControlまたはETagを設定しません。すべての呼び出しはバックエンドに到達します。キャッシュが必要な場合は、お客様側で追加してください。

ターゲットのResponse Headers

ターゲットサイトが返したヘッダーは、FourA APIレスポンスにはありません。これらはheadersフィールドとしてJSONエンベロープ内で返されます。SingleおよびProxyエンドポイントの場合、これはホップごとのヘッダーオブジェクトの配列です(リダイレクトステップごとに1つのエントリ)。Browserエンドポイントの場合、これは最終的なレスポンスヘッダーのフラットなオブジェクトです。

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

特定のターゲットヘッダーが必要な場合は、API呼び出し自体のHTTPレスポンスからではなく、エンベロープのheadersフィールドから読み取ってください。