本文へスキップ
Sursa Developers

POST/v1/cards/bulk

カードに一括操作を実行する

bulk_cards

選択したカードに一括操作を実行します。権限はカードごとに確認されます：コレクションでのロールとデータプロファイルです（破壊的な操作には、ドキュメントのすべての部分へのアクセスが必要です）。操作できないカードは理由を付けてスキップされます。各変更はカードの監査ログに記録され、さらに結果を含むcards.bulkの記録が1件追加されます。

フォルダーの操作：
- folder_moveはparams.folder_id（必須）でカードをフォルダーに入れ、params.from_folder_idを渡した場合はそのフォルダーから外します（開いているフォルダーからの移動）。
- folder_removeはparams.folder_idのフォルダーからカードを外します。カードはコレクションに残ります。

フォルダーはリクエストごとに一度だけ確認されます：存在しないかアクセスできないフォルダーは404 folders.not_found、フォルダーに対するCOLLECTION_EDIT_CARDS権限がない場合は403 authz.forbidden、folder_idがない場合や別のコレクションのfrom_folder_idは400 cards.bulk_invalidを返します。カードごとの扱い：CARD_EDITがないカードはno_writeとしてスキップ、フォルダーと異なるコレクションのカードはcollection_mismatchとしてスキップ、すでに目的の場所にあるカードはunchangedとして報告されます。

認証

AuthorizationヘッダーでAPIキーを送信します：Authorization: Bearer <キー>。

ヘッダーパラメーター

  • Idempotency-Keystring

    書き込みを安全に再試行するためのキー：1〜255文字の印字可能なASCII文字で、論理的な操作ごとにUUID v4を使うことを推奨します。同じキーで24時間以内に再試行しても操作は再実行されず、保存済みのレスポンス（ステータス、ヘッダー、ボディ）がIdempotency-Replayed: trueヘッダー付きで返されます。同じキーでメソッド、パス、Content-Type、ボディのいずれかが異なる場合は409 api.idempotency_mismatchを返し、最初のリクエストがまだ実行中の場合は409 api.idempotency_in_progressをRetry-After: 1付きで返します。5xxまたは429のレスポンスの後はキーが解放され、再試行で操作がもう一度実行されます。キーの有効範囲は、組織と呼び出し元（APIキー、ユーザー、カスタムソースのソースキー）の組み合わせです。

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    adminロールのAPIキー専用です。データプロファイル<profile>[:viewer|verifier|editor]（例：employee:viewer）としてリクエストを実行します。インストールキーではこのヘッダーを使えません（403）。

Cookieパラメーター

  • kb_view_asstring

    セッションの「View as」モードのCookie。POST /auth/view-asで設定し、DELETE /auth/view-asで解除します。

リクエストボディ

application/json

オブジェクト：BulkRequest

  • idsarray of string必須

    items ≥ 1, items ≤ 500

  • actionBulkAction必須
  • paramsobject

レスポンス

200成功時のレスポンス

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

  • Idempotency-Replayed

    trueは、このIdempotency-Keyの保存済みのレスポンスが再送されたことを示します：操作は再実行されていません。

application/json

オブジェクト：BulkResult

  • countsobject必須
    フィールド
    • doneinteger必須
    • reasonsobject必須
      フィールド
      • admin_onlynumber
      • collection_mismatchinteger
      • connectornumber
      • failedinteger
      • needs_usernumber
      • no_verifynumber
      • no_writenumber
      • not_foundnumber
      • partial_accessnumber
      • processinginteger
      • same_collectionnumber
      • sensitive_lowernumber
      • target_needs_reindexnumber
      • unchangedinteger
    • skippedinteger必須
  • donearray of string必須
  • fileAttachment
  • jobsarray of integer
  • skippedarray of BulkSkipped必須
400リクエストが無効です：パラメーターの値またはオブジェクトの状態により、この操作を実行できません（`detail`はメッセージ）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

401認証情報が送信されていない（セッションCookieもAPIキーもない）か、キーが見つかりません。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

403この操作は許可されていません：ロールの権限が足りない、コレクションやカードへのアクセス権がない、リクエストが「View as」モードで実行されている、または組織が停止中か削除済みです（`detail`は`code: org_suspended | org_deleted`を持つオブジェクト）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

404オブジェクトが存在しないか、アクセスできません。APIは、アクセスが制限されたオブジェクトの存在を明かしません。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

422バリデーションエラー：ボディまたはパラメーターがスキーマに一致しない（`detail`はバリデーションエラーのリスト）、またはパラメーターの値が範囲外です（`detail`はメッセージ）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

429リクエストが多すぎる（`api.rate_limited`）、組織の1分・1日・1か月のクォータを使い切った（`api.quota_exceeded`。`error.details`には`quota`、`limit`、`reset_at`が含まれます）、組織の上限に達した、または回答サービスが混雑しています（`answers.engine_busy`）。`Retry-After`ヘッダーの時間だけ待ってください。

レスポンスヘッダー

  • Retry-After

    リクエストを再試行するまでに待つ秒数。

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

エラーコード

すべてのリクエストに共通のコードに加えて、このエンドポイントがerror.codeで返すことのあるコード。

安全な再試行

POSTとPATCHのたびにIdempotency-Keyヘッダー（UUIDなど）を送信してください。24時間以内に同じキーで再試行すると、リクエストをもう一度実行せずに、保存済みのレスポンスが返ります。

レート制限

レスポンスには、RateLimitヘッダーとRateLimit-Policyヘッダー、以前のX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれます。429レスポンスにはRetry-After（秒）が含まれます。その時間だけ待ってから再試行してください。

← cards · APIリファレンス