> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob 共有の作成

> POST /v1/shares で共有リンクを作成します: 最大 30 日間有効で取り消しが可能、任意でダウンロード回数の上限を設定でき、Pro と Enterprise ではパスワードも設定できます。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  アカウントの API キーです。これは[アカウント設定](https://squarecloud.app/ja/account/security)で確認できます。
</ParamField>

共有の作成は、1 つのファイルを人に渡すためのリンク (`https://files.squarecloud.dev/s/...`) を作成します: クライアント、チーム、テスターなどに渡すためのものです。公開ファイルとプライベートファイルの両方で機能し、最大 30 日間有効で、いつでも取り消すことができ、ファイルのダウンロード回数を制限できます。**Pro と Enterprise** では、パスワードを要求することもできます。`blob:write` スコープが必要です。

リンクを開くとファイルがダウンロードされます。パスワード保護されたリンクでは、まず訪問者の言語でパスワードを求めるページが表示されます。リンクはファイルの現在の id に紐付けられています: ファイルを削除、移動したり公開範囲を変更したりすると、リンクはすぐに `404` を返し、ダウンロード回数は消費されません。一時リンクとの比較については[リンクと共有](/ja/blob-reference/links-and-sharing)を参照してください。

<ParamField body="object" type="string" required>
  共有するファイルの id。
</ParamField>

<ParamField body="expires_in" type="number" default="86400">
  リンクの有効期間。60〜2592000 秒 (30 日) です。
</ParamField>

<ParamField body="max_downloads" type="number">
  リンクで許可されるダウンロード回数。1〜10000 です。使い切ると `410` を返します。指定しない場合は上限はありません。
</ParamField>

<ParamField body="password" type="string">
  訪問者がダウンロード前に入力する必要がある 8〜128 文字のパスワード。Pro と Enterprise のみ。
</ParamField>

<Warning>**公開**ファイルの場合、リンクは恒久的な公開 URL へリダイレクトし、リンクを開いた人はその URL を使い続けられます。パスワード、ダウンロード回数の上限、有効期限が本当に保護できるのは**プライベート**ファイルだけです。</Warning>

### 制限

<Note>
  * 1 分間に 30 リンク (`RATE_LIMITED`、429)、アカウントあたり有効なリンクは最大 1000 件 (`TOO_MANY_SHARES`、409)。
  * 各リンクは IP あたり 1 分間に 120 回のアクセスを受け付けます。誤ったパスワードは IP ごと、リンクごとに制限されます。
  * プライベートファイルのダウンロードは一時リンクを経由します: IP あたり 1 分間に 60 リクエスト、およびアカウント全体の制限。ファイルを多くの人に渡すには、ファイルを公開してください。
</Note>

### レスポンス

`201 Created` を返します。

<ResponseField name="status" type="string">
  成功した場合は "success"、失敗した場合は "error" です。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを切り替え">
    <ResponseField name="id" type="string">
      共有 id。[共有の削除](/ja/blob-reference/endpoint/shares-delete)で使用します。
    </ResponseField>

    <ResponseField name="url" type="string">
      配布するリンク。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      リンクの有効期限。
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      ダウンロード回数の上限、または `null`。
    </ResponseField>

    <ResponseField name="password" type="boolean">
      リンクがパスワードを要求するかどうか。
    </ResponseField>

    <ResponseField name="object" type="string">
      共有されたファイルの id。
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      ファイルが公開されている場合は `true`: 公開 URL を知っていれば誰でも引き続きダウンロードできるため、共有を取り消したり、回数を制限したり、パスワードで保護したりしても、ファイル自体へのアクセスは制限されません。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/shares' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "expires_in": 604800,
      "max_downloads": 5
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://blob.squarecloud.app/v1/shares', {
    method: 'POST',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
      expires_in: 7 * 24 * 60 * 60,
      max_downloads: 5,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
      "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
      "expires_at": "2026-10-02T12:00:00.000Z",
      "max_downloads": 5,
      "password": false,
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "object_is_public": false
    }
  }
  ```
</ResponseExample>

### エラー

| コード                     | HTTP | 発生する状況                                    |
| ----------------------- | ---- | ----------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` がない、形式が正しくない、またはあなたのものではない。      |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` が 60〜2592000 の整数ではない。        |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` が 1〜10000 の整数ではない。        |
| `INVALID_PASSWORD`      | 400  | パスワードが 8〜128 文字ではない。                      |
| `UPGRADE_REQUIRED`      | 403  | パスワードには Pro または Enterprise が必要。           |
| `OBJECT_NOT_FOUND`      | 404  | ファイルが存在しない。                               |
| `TOO_MANY_SHARES`       | 409  | アカウントに 1000 件の有効なリンクがある。先にいくつかを取り消してください。 |
| `RATE_LIMITED`          | 429  | 1 分間に 30 リンクを超えた。                         |