シート

アカウントのBearerトークンを使って、Google Sheetやアップロードしたブック全体のリンクを変換できます。CSVを入力した場合も、出力は常に.xlsxです。リンクで説明するように、リンクは元の位置で置換され、自分のアカウントに紹介実績が記録されます。任意でcampaignとlabelも指定できます。

Google Sheetの入力セクションのリンクをコピー

NinjaBuyが読み取れるGoogle SheetsのURLを送信してください。変換では表示プレビューだけでなくすべてのタブを読み取り、このジョブ用のスナップショットを固定します。

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

XLSXまたはCSVの入力セクションのリンクをコピー

まずアップロードを予約します。filenameは.xlsxまたは.csvで終わり、前後の空白を除去した後で1〜255文字である必要があります。bytesはファイルの正確なバイト数で、1〜20,971,520です。

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

201レスポンスにはupload_id、署名付きPUT用url、expires_at（Unixエポックからのミリ秒）、max_bytes、request_idが含まれます。予約は15分後に期限切れになります。返されたURLに生のファイルをPUTし、そのアップロードIDを送信してください。

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

直接のPUTには、ストレージサービスのレスポンス仕様が適用されます。NinjaBuyは変換の送信時にアップロードされたバイト列を検証します。不明なアップロードIDや別のアカウントのIDは404を返します。保存されたオブジェクトのバイト数は申告した値と一致する必要があります。申告したサイズまたは上限を超えるオブジェクトは413 upload-too-largeを返し、申告したサイズより小さい（途中で切れた）オブジェクトはバイト数の不一致の説明とともに422 invalid-workbookを返します。これらの検証はダウンロード前に行われ、メタデータの検証後にバイト列が変わった場合にも適用されます。拒否された元のアップロードファイルは削除され、受け付けられた元のアップロードファイルは検証済みのスナップショットが記録された時点で削除されます。

urlまたはupload_idのどちらか一方だけを送信してください。どちらも任意のcampaignとlabelに対応し、asyncフィールドは不要です。両方のPOSTルートでIdempotency-Keyを使用でき、それぞれ共通の毎分30回の作成枠を1回消費します。配下のリンク変換は追加の枠を消費しません。

ジョブとダウンロードセクションのリンクをコピー

シートの送信は、Location: /api/v1/jobs/JOB_ID、Retry-After: 5と次の本文を含む202を返します。

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

poll_after_secondsに従い、doneまたはfailedになるまで同じアカウントのトークンでジョブをポーリングしてください。完了したjob.resultにはkind: "sheet_conversion"、countsと、15分間有効な署名付きdownload_urlが含まれます。再度ポーリングすると新しいダウンロード署名を取得できます。失敗したジョブにはerrorがあり、部分的なダウンロードは提供されません。

Google スプレッドシートの場合、job.result に copy_url が含まれることもあります。これはリンクをあなたのリンクに置き換えた Google スプレッドシートの正確なコピーへの閲覧専用リンクで、リンクを知っている人は ファイル → コピーを作成 で自分用のコピーを保存できます。copy_notes には、そのコピーを見る人が知っておくべきこと(たとえば =IMAGE() で作成した画像は、自分のコピーで アクセスを許可 を一度クリックする必要があること)が入ります。download_url は引き続き XLSX を返します。copy_counts にはコピーについての同じ件数が入ります。XLSX を作成できない場合、結果には copy_url が残り、download_url はなく、copy_notes にその理由が入ります。download_notes には、XLSX がシートから保持できないもの(グラフや 1 つのセル内の 2 つ目のリンクなど)が 1 行ずつ入ります。

スナップショットと結果ファイルは、ジョブの完了または失敗から7日間保持されます。クリーンアップ後もジョブのステータスと件数は確認できますが、job.result.download_urlは省略されます。共有スナップショットは、別のジョブが必要としている間は保持されます。放置された元のアップロードファイルは、アップロード予約の期限切れから1時間後に削除されます。検証済みのアップロードからジョブが開始されなかった場合、そのスナップショットは予約の期限切れから7日後に削除されます。クリーンアップは1時間ごとに実行されます。

カバレッジはlinks_found = converted + sum(left_by_host) + unresolvedを満たします。SNSリンク、Google Sheetsリンク、同じブック内の移動、既存のNinjaBuyリンクは変更しません。出力を書き込む前に、すべての変換候補に回答が必要です。回答が不足するとジョブは失敗します。

ブックで保持される内容セクションのリンクをコピー

出力には、解析されたグリッドに表現されているスタイル、セル結合、行と列のサイズ、画像が保持されます。リッチテキストの書式区間はセルのハイパーリンクがないセルで保持され、リンク付きセルには1つのテキストラベルとハイパーリンクが使用されます。ブックは新たにシリアライズされるため、グラフ、マクロ、およびそのグリッドの範囲外の機能は保持されません。

XLSXでは1つのセルに1つのハイパーリンクを設定できます。変換では、隣に2つ目のリンクを追加せず、元の位置でリンクを置換します。1つのセルに画像以外の異なるリンク先が2つ以上ある場合は、最初のリンク先をハイパーリンクとして残し、残りをセルのメモに記載するため、リンク先は失われません。

制限セクションのリンクをコピー

パーサーまたは書き込み処理の上限を超えると明示的に失敗します。invalid-workbook、upload-expired、upload-too-largeについてはエラーをご覧ください。