Amazon S3、Google Cloud Storage、BigQuery への結果エクスポート

エクスポートは 1 時間ごと、または UTC の 1 日ごとに、その期間の結果を gzip 圧縮の JSON Lines として Amazon S3 や Google Cloud Storage のバケットに書き込むか、BigQuery テーブルのパーティションに読み込みます。データウェアハウスは他のソースと同じ方法で読み込めるため、ポーリングのループは不要です。バケットまたはデータセットに、当社のエクスポート用 ID への書き込み権限を付与するだけで、キーやパスワードを共有する必要はありません。このページのキー、バケット、アカウント ID、ロールはすべて例です。

エクスポートされるデータ

データセット	行	期間の基準	同じフィールド
`tasks`	`COMPLETED` または `FAILED` で終了したアカウントのすべてのタスク	`completedAt`	`GET /v1/async/task/{id}` と webhook
`monitor_results`	アカウントのすべてのモニターが採点したすべての回答	`ranAt`	`GET /v1/monitors/{id}/results?includeEvidence=true`

アカウントのどのキーで送信したタスクも、Playground とモニターが作成したタスクもすべて含まれます。1 つの期間には、時刻が [windowStart, windowEnd) に入る行だけが正確に入ります。 配信のタイミング。 期間は閉じてから 10 分後に配信対象になるため、境界で確定した課金も含まれます。配信対象の期間は 15 分ごとに実行されるジョブが取り上げるので、通常は期間が閉じてから 10〜25 分後に配信が始まります。

エクスポートを設定する

エクスポート用 ID を確認する

curl https://api.querying.ai/v1/exports/identity \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "success": true,
  "identity": {
    "accountKey": "acct_3f9a1c2b7d4e",
    "gcp": { "serviceAccount": "querying-export@example-project.iam.gserviceaccount.com" },
    "aws": {
      "federatedPrincipal": "accounts.google.com",
      "audience": "117000000000000000001",
      "oaud": "querying-result-export",
      "roleSessionName": "querying-acct_3f9a1c2b7d4e",
      "trustPolicy": { "Version": "2012-10-17", "Statement": ["..."] }
    }
  }
}

accountKey はお客様のフォルダーとテーブルの名前です。当社が書き込むすべてのパスとテーブルにこの値が入るため、複数の querying.ai アカウントが 1 つのバケットやデータセットを共有しても、それぞれ自分のファイルだけを書き込みます。権限は上の例ではなく、実際のレスポンスに表示された ID に付与してください。

権限を付与する

配信先へのアクセス権を ID に付与します。S3、Cloud Storage、BigQuery については権限を付与するを参照してください。

エクスポートを作成する

POST /v1/exports が権限を確認し、エクスポートを保存します。エクスポートを作成するを参照してください。

最初の配信を確認する

GET /v1/exports/{id}/runs が各期間とそのステータスを一覧表示します。配信履歴を参照してください。

権限を付与する

Amazon S3

当社の Google ID が引き受けられる IAM ロールを AWS アカウントに作成します。ID のレスポンスにある trustPolicy をロールの信頼ポリシーとして使います。このポリシーは、当社のエクスポート用 ID がお客様アカウントのセッション名で要求した場合だけを受け入れます。

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "accounts.google.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": { "StringEquals": {
      "accounts.google.com:aud": "117000000000000000001",
      "accounts.google.com:oaud": "querying-result-export",
      "sts:RoleSessionName": "querying-acct_3f9a1c2b7d4e"
    } }
  }]
}

ロールがプレフィックス配下に書き込めるよう、権限ポリシーをアタッチします。

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::acme-geo/querying/*"
  }]
}

バケットがカスタマー管理の KMS キーで暗号化している場合は、そのキーに kms:GenerateDataKey も許可します。

Google Cloud Storage

バケットでエクスポート用サービスアカウントに Storage Object User（roles/storage.objectUser）を付与します。ファイルを作成し、期間を再送したときにファイルを置き換えます。

gcloud storage buckets add-iam-policy-binding gs://acme-geo \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"

付与をお客様のフォルダーに限定するには、IAM 条件 resource.name.startsWith("projects/_/buckets/acme-geo/objects/querying/acct_3f9a1c2b7d4e/") を追加します。

BigQuery

データセットでエクスポート用サービスアカウントに BigQuery Data Editor（roles/bigquery.dataEditor）を付与します。読み込みジョブは当社のプロジェクトで実行するため読み込み費用はかからず、お支払いはストレージと実行するクエリの分だけです。

bq add-iam-policy-binding \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataEditor" acme-analytics:geo_raw

エクスポートを作成する

エンジンのスコープがない API キーを使ってください。エクスポートはアカウントのすべての結果を送るため、一部のエンジンに限定されたキーでは 403 KEY_SCOPE になります。

curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "s3",
      "bucket": "acme-geo",
      "region": "us-east-1",
      "roleArn": "arn:aws:iam::123456789012:role/querying-export",
      "prefix": "querying"
    },
    "interval": "daily",
    "data": ["tasks", "monitor_results"]
  }'

curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "type": "gcs", "bucket": "acme-geo", "prefix": "querying" },
    "interval": "hourly",
    "data": ["tasks"]
  }'

curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "type": "bigquery", "projectId": "acme-analytics", "datasetId": "geo_raw" },
    "interval": "daily",
    "startAt": "2026-10-01T00:00:00Z"
  }'

フィールド	必須	説明
`destination.type`	はい	`s3`、`gcs` または `bigquery`。
`destination.bucket`	S3、GCS	バケット名。
`destination.prefix`	いいえ	バケット内のフォルダー。最大 256 文字の相対パスです（先頭の `/`、`.` や `..` のセグメントは不可）。末尾に `/` が付加されます。
`destination.region`	S3	バケットの AWS リージョン（例: `us-east-1`）。
`destination.roleArn`	S3	権限を付与するで作成したロール。`arn:aws:iam::<account>:role/<name>` の形式です。
`destination.projectId`, `destination.datasetId`	BigQuery	Google Cloud のプロジェクトとデータセット。
`interval`	いいえ	`hourly` または `daily`（既定）。エクスポートの存続期間中は変更できません。
`data`	いいえ	`tasks`、`monitor_results`、または両方（既定）。
`startAt`	いいえ	ISO 8601 の時刻。未来は指定できず、最大 30 日前までです。その時刻を含む期間が最初の期間になります。既定は現在です。

保存する前に、エクスポートは権限を確認します。S3 と Cloud Storage では <prefix><accountKey>/_querying/connection-check.json を書き込み、BigQuery ではデータセットを読み取ってそのロケーションを記録します。確認に失敗した場合は何も保存されません。1 アカウントあたり最大 10 件のエクスポートを作成できます。レスポンスは 201 で、エクスポートを返します。

{
  "success": true,
  "export": {
    "id": "6a1d0f3c-...",
    "destination": {
      "type": "bigquery",
      "projectId": "acme-analytics",
      "datasetId": "geo_raw",
      "location": "US",
      "tables": [
        "acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e",
        "acme-analytics.geo_raw.querying_monitor_results_v1_acct_3f9a1c2b7d4e"
      ]
    },
    "interval": "daily",
    "data": ["tasks", "monitor_results"],
    "enabled": true,
    "schemaVersion": 1,
    "nextWindowStart": "2026-10-01T00:00:00.000Z",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "deliveredThrough": null,
    "failedRuns": 0,
    "retryingRuns": 0
  }
}

S3 と Cloud Storage では、destination はバケットの設定をそのまま返し、ファイルが届くフォルダー path（例: s3://acme-geo/querying/acct_3f9a1c2b7d4e/、gs://acme-geo/querying/acct_3f9a1c2b7d4e/）を加えます。nextWindowStart は次に計画される期間の開始時刻です。

エラー

ステータス	コード	原因
`400`	`VALIDATION_ERROR`	JSON が不正か、フィールドが範囲外です。メッセージにフィールド名が示されます（例: `destination.region: region is the bucket's AWS region, e.g. us-east-1`）。
`403`	`KEY_SCOPE`	API キーが一部のエンジンに限定されています。
`409`	`EXPORT_LIMIT`	アカウントにすでに 10 件のエクスポートがあります。
`422`	`EXPORT_DESTINATION_UNREACHABLE`	接続確認に失敗しました。メッセージにストレージ側の理由が入ります。通常は権限の不足です。
`502`	`EXPORT_CHECK_FAILED`	配信先に到達できませんでした。もう一度お試しください。
`503`	`EXPORTS_NOT_CONFIGURED`	この種類の配信先へのエクスポートは利用できません。

ファイルとテーブル

S3 と Cloud Storage のファイル

s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz
s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/_manifest.json
s3://acme-geo/querying/acct_3f9a1c2b7d4e/monitor_results/v1/dt=2026-10-08/hour=13/part-00000.jsonl.gz

ディレクトリは Hive パーティション（dt=、時間別エクスポートなら hour=）に従うため、Athena、BigQuery 外部テーブル、Spark が列として読み取ります。
v1 はスキーマのバージョン（エクスポートの schemaVersion）です。列を壊す変更は v2 として並べて提供します。
1 つの期間は、時刻順に最大 100,000 行ずつの part ファイルに分かれます。
_manifest.json は最後に書き込みます。マニフェストが存在する期間を読み込み、part の一覧はマニフェストから読んでください。

{
  "schemaVersion": 1,
  "data": "tasks",
  "windowStart": "2026-10-08T00:00:00.000Z",
  "windowEnd": "2026-10-09T00:00:00.000Z",
  "rows": 20000,
  "files": [{ "key": "querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz", "rows": 20000, "bytes": 1990096 }],
  "deliveredAt": "2026-10-09T00:16:02.114Z"
}

マニフェストの rows は part ファイルの行数と一致し、配信履歴の run の rows とも一致します。ファイル名は期間だけで決まるため、再送した期間は同じオブジェクトを置き換えます。

BigQuery テーブル

BigQuery エクスポートは querying_tasks_v1_<accountKey> と querying_monitor_results_v1_<accountKey> に読み込みます。テーブルは最初の読み込みで作成され、completedAt または ranAt でパーティション分割されます（日別、時間別エクスポートは時間別）。期間ごとに自分のパーティションを置き換えるため、再送した期間が二重になることはありません。payload、response、sources、scoringContext は JSON 列です。

SELECT taskType, JSON_VALUE(payload.prompt) AS prompt, JSON_VALUE(response.text) AS answer
FROM `acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e`
WHERE DATE(completedAt) = "2026-10-08" AND status = "COMPLETED";

行スキーマ (v1)

`tasks`

フィールド	型	BigQuery の型	説明
`id`	string	`STRING`	タスク ID。
`taskType`	string	`STRING`	エンジン（例: `CHATGPT`）。
`status`	string	`STRING`	`COMPLETED` または `FAILED`。
`priority`	integer	`INT64`	送信した値。
`idempotencyKey`	string or null	`STRING`	送信した場合はお客様の冪等キー。
`createdAt`, `completedAt`	timestamp	`TIMESTAMP`	UTC、マイクロ秒精度。
`monitorId`	string or null	`STRING`	実行したモニター。
`creditsCharged`	decimal	`NUMERIC`	タスクに課金されたクレジット。小数点以下 2 桁まで（例: `1.25`）。失敗したタスクは `0`。整数ではなく小数として読んでください。
`payload`	object	`JSON`	送信した payload。
`response`	object or null	`JSON`	`GET /v1/async/task/{id}` が返す結果。タスクが失敗した場合は `null`。
`error`	string or null	`STRING`	コードで始まる失敗理由。完了時は `null`。

`monitor_results`

フィールド	型	BigQuery の型	説明
`id`, `monitorId`, `taskId`	string	`STRING`	結果、モニター、タスクの ID。
`engine`, `prompt`	string	`STRING`	どこで何を質問したか。
`mentioned`, `cited`	boolean	`BOOL`	ブランドの言及、お客様ドメインの引用。
`position`	integer or null	`INT64`	最初のブランド言及の文字位置。
`competitorHits`	string array	`STRING`（repeated）	回答に出た競合。
`sources`	array	`JSON`	`{url, label, position}` 形式の引用。
`answerText`	string or null	`STRING`	スコアの読み取りに使った回答。
`scoringContext`	object or null	`JSON`	当時の採点定義。
`latitude`, `longitude`	number or null	`FLOAT64`	位置モニターが質問した地点。
`ranAt`	timestamp	`TIMESTAMP`	UTC、マイクロ秒精度。

配信履歴

データセットごとの 1 期間が 1 つの run です。新しい順に一覧表示します。

curl "https://api.querying.ai/v1/exports/$EXPORT_ID/runs?status=failed" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "success": true,
  "runs": [{
    "id": "3c9e1b7a-...",
    "data": "tasks",
    "windowStart": "2026-10-08T00:00:00.000Z",
    "windowEnd": "2026-10-09T00:00:00.000Z",
    "status": "failed",
    "attempts": 8,
    "nextAttemptAt": null,
    "rows": null,
    "bytes": null,
    "files": [],
    "error": "S3 PutObject s3://acme-geo/... failed: HTTP 403 AccessDenied: Access Denied",
    "deliveredAt": null
  }],
  "nextCursor": null
}

`status`	意味
`pending`	配信待ち、または失敗後の再試行待ち。`nextAttemptAt` にその時刻が入ります。
`running`	配信中です。
`delivered`	書き込み済みです。`rows`、`bytes`、`files`、`deliveredAt` が設定されます。
`failed`	8 回の試行がすべて失敗しました。再送するまで何も起きません。

status、data（tasks または monitor_results）、limit（1〜200、既定値 50）で絞り込めます。次のページは nextCursor を cursor として渡してください。

自動再試行。 失敗した試行は 15 分後に再試行され、その後は間隔を倍にしながら最大 12 時間間隔で、合計 8 回まで試行します。error にはストレージ側の理由が入るため、権限の不足はまずここに表示されます。
期間を再送する。 POST /v1/exports/{id}/runs/{runId}/retry は期間を今すぐ送ります。権限を直した後の失敗した期間や、書き直したい配信済みの期間に使います。attempts をリセットし、run を pending として返します。配信中の run には 409 EXPORT_RUN_RUNNING を返します。
エクスポートの健全性。 GET /v1/exports と GET /v1/exports/{id} は deliveredThrough（最後に配信された期間の終わり）、failedRuns、retryingRuns（少なくとも 1 回失敗した pending の run）を加えて返します。

一時停止、再開、削除

PATCH /v1/exports/{id} に {"enabled": false} を送るとエクスポートを一時停止します。{"enabled": true} で再開し、抜けた期間を最大 30 日前まで追って送ります。
DELETE /v1/exports/{id} はエクスポートを停止します。配信済みのファイルとパーティションはお客様のストレージに残ります。
配信先、間隔、データセットは変更できません。新しいエクスポートを作成し、古いものを削除してください。

エンドポイント

メソッドとパス	用途
`GET /v1/exports/identity`	権限を付与する ID とお客様のアカウントキー
`POST /v1/exports`	配信先を接続する
`GET /v1/exports`	配信の健全性付きのエクスポート一覧
`GET /v1/exports/{id}`	1 件のエクスポート
`PATCH /v1/exports/{id}`	一時停止または再開
`DELETE /v1/exports/{id}`	エクスポートを停止する
`GET /v1/exports/{id}/runs`	配信履歴
`POST /v1/exports/{id}/runs/{runId}/retry`	期間を再送する

所有していないエクスポートには 404 NOT_FOUND を返します。

はじめに

基本概念

回答エンジン

検索とウェブデータ

リクエストオプション

リサーチ

GEOモニタリング

アカウントとデータ

Amazon S3、Google Cloud Storage、BigQuery への結果エクスポート

エクスポートされるデータ

エクスポートを設定する

権限を付与する

Amazon S3

Google Cloud Storage

BigQuery

エクスポートを作成する

エラー

ファイルとテーブル

S3 と Cloud Storage のファイル

BigQuery テーブル

行スキーマ (v1)

`tasks`

`monitor_results`

配信履歴

一時停止、再開、削除

エンドポイント

​エクスポートされるデータ

​エクスポートを設定する

​権限を付与する

​Amazon S3

​Google Cloud Storage

​BigQuery

​エクスポートを作成する

​エラー

​ファイルとテーブル

​S3 と Cloud Storage のファイル

​BigQuery テーブル

​行スキーマ (v1)

​tasks

​monitor_results

​配信履歴

​一時停止、再開、削除

​エンドポイント

エクスポートされるデータ

エクスポートを設定する

権限を付与する

Amazon S3

Google Cloud Storage

BigQuery

エクスポートを作成する

エラー

ファイルとテーブル

S3 と Cloud Storage のファイル

BigQuery テーブル

行スキーマ (v1)

`tasks`

`monitor_results`

配信履歴

一時停止、再開、削除

エンドポイント