> ## 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.

# Objekte

> Liste, prüfe, verlinke, aktualisiere, lösche, kopiere und verschiebe Objekte in Blob Storage mit @squarecloud/blob.

<Note>
  Objekt-IDs sind opak (`pub/...`, `prv/...`). Speichere sie so, wie sie zurückgegeben werden, baue oder parse sie nie und ersetze deine gespeicherte ID, wann immer [`update()`](#objekte-aktualisieren) eine neue zurückgibt. Siehe [Objekt-IDs](/de/sdks/blob/client#objekt-ids).
</Note>

## Auflisten

`list()` ist ein **Async Generator**, der dem Cursor durch alle Seiten folgt. Die Reihenfolge ist nicht garantiert.

```typescript theme={"system"}
for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}
```

`listPage()` ruft **eine Seite** ab. Verwende es für manuelle Paginierung oder um `folders` zu erhalten:

```typescript theme={"system"}
const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}
```

| Option      | Typ       | Beschreibung                                                       |
| ----------- | --------- | ------------------------------------------------------------------ |
| `prefix`    | `string`  | Nur Objekte unter diesem Präfix.                                   |
| `delimiter` | `"/"`     | Gruppiert nach Ordner: Die Seite gibt zusätzlich `folders` zurück. |
| `private`   | `boolean` | Nur private (`true`) oder öffentliche (`false`) Objekte.           |
| `limit`     | `number`  | Objekte pro Seite, 1 bis 1000 (Standard 1000).                     |
| `cursor`    | `string`  | Nur `listPage()`: das `continuationToken` der vorherigen Seite.    |

Eine Seite hat `objects`, `folders` (nur mit `delimiter`) und `continuationToken` (**fehlt auf der letzten Seite**). Jedes aufgelistete Objekt hat `id`, `size`, `created_at`, `expires_at`, `private`, `url` und `etag`. Siehe [Object List](/de/blob-reference/endpoint/list).

## Objektdetails

```typescript theme={"system"}
const info = await blob.info(id);
```

Gibt `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` und `legacy` zurück. Siehe [Object Info](/de/blob-reference/endpoint/info).

<Note>
  `created_at` ist der Zeitpunkt der letzten Änderung im Speicher: Ein Update, das das Objekt kopiert (Sichtbarkeit, Ablauf, Header), setzt ihn zurück.
</Note>

## Download-Links

```typescript theme={"system"}
const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });
```

* Ein **öffentliches** Objekt erhält seine **dauerhafte CDN-URL**, mit `expires_at: null`.
* Ein **privates** Objekt, oder jeder Aufruf mit `disposition` oder `filename`, erhält einen **temporären Link**, der `expires` Sekunden gültig ist (bis zu 24 Stunden).

<Warning>
  Ein temporärer Link **kann nicht widerrufen werden**. Für widerrufbare, passwortgeschützte oder in der Anzahl der Downloads begrenzte Links verwende eine [Freigabe](/de/sdks/blob/sharing).
</Warning>

| Option        | Typ                          | Beschreibung                                                     |
| ------------- | ---------------------------- | ---------------------------------------------------------------- |
| `expires`     | `number`                     | Lebensdauer des Links in Sekunden, 60 bis 86400 (Standard 3600). |
| `disposition` | `"inline"` \| `"attachment"` | Überschreibt `Content-Disposition` für diesen Link.              |
| `filename`    | `string`                     | Dateiname, unter dem der Browser den Download speichert.         |

Das Ergebnis hat `url`, `expires_at`, `private`, `size` und `content_type`. Siehe [Object Download](/de/blob-reference/endpoint/download).

## Objekte aktualisieren

`update()` ändert Sichtbarkeit, Ablauf, Cache, Disposition oder Metadaten **eines Objekts oder von bis zu 50**. Die Methode **gibt immer ein Array zurück**, ein Ergebnis pro Objekt, und jedes Ergebnis meldet seinen eigenen Erfolg in `ok`.

```typescript theme={"system"}
const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}
```

| Änderung        | Typ                                      | Beschreibung                                                    |
| --------------- | ---------------------------------------- | --------------------------------------------------------------- |
| `private`       | `boolean`                                | Macht das Objekt privat oder öffentlich. **Ändert die ID.**     |
| `expire`        | `string \| null`                         | Neuer Ablauf; `null` entfernt ihn. **Ändert die ID.**           |
| `cache_control` | `string \| null`                         | `null` entfernt es.                                             |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` entfernt sie.                                            |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` entfernt einen Schlüssel; `null` entfernt alle. |

Ein erfolgreiches Ergebnis (`ok: true`) hat `object` (die von dir gesendete ID), `changed`, `id` (**die ID nach der Änderung**), `private`, `url`, `expires_at` und `size`. Ein fehlgeschlagenes Ergebnis (`ok: false`) hat `object` und `code`. Ein Batch wirft bei Fehlern einzelner Objekte nicht. Siehe [Object Update](/de/blob-reference/endpoint/update).

## Löschen

Das Löschen erfolgt **sofort und endgültig**: Es gibt keinen Papierkorb.

```typescript theme={"system"}
// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);
```

| Aufruf          | Rückgabe                         | Bei einem fehlenden Objekt                                        |
| --------------- | -------------------------------- | ----------------------------------------------------------------- |
| `delete(id)`    | `void`                           | Wirft `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).                |
| `delete([ids])` | `{ deleted, not_found, failed }` | Wird in `not_found` gemeldet. `failed` listet `{ id, code }` auf. |

Mit **einer einzelnen ID in einem Array** gibt das SDK trotzdem `{ deleted, not_found, failed }` zurück: Ein fehlendes Objekt landet in `not_found`, und `DELETE_FAILED` oder `PREFIX_NOT_ALLOWED` landen in `failed`, statt geworfen zu werden. Jeder andere Fehler (Authentifizierung, Rate Limit, Netzwerk) wird weiterhin geworfen. Siehe [Delete Objects](/de/blob-reference/endpoint/delete).

## Kopieren, Verschieben und Umbenennen

Beides läuft auf dem Server, ohne die Datei herunterzuladen.

```typescript theme={"system"}
// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;
```

`move(source, destination, options)` ist `copy()` mit `move: true`.

| Zielfeld        | Typ              | Beschreibung                                                               |
| --------------- | ---------------- | -------------------------------------------------------------------------- |
| `name`          | `string`         | Erforderlich. Name **ohne Endung**: Das Ziel behält die Endung der Quelle. |
| `prefix`        | `string`         | Präfix des Ziels.                                                          |
| `private`       | `boolean`        | Sichtbarkeit des Ziels.                                                    |
| `security_hash` | `boolean`        | Hängt `_<hash>` an den Namen an.                                           |
| `expire`        | `string \| null` | Weggelassen bleibt der Ablauf der Quelle erhalten; `null` entfernt ihn.    |

| Option      | Akzeptiert von     | Beschreibung                                                                                |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------- |
| `overwrite` | `copy()`, `move()` | `true` ersetzt ein vorhandenes Objekt am Ziel.                                              |
| `move`      | `copy()`           | `true` entfernt die Quelle, sobald die Kopie erfolgreich war (wie ein Aufruf von `move()`). |

Das Ergebnis hat `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` und `replaced`. Siehe [Object Copy](/de/blob-reference/endpoint/copy).

<Note>
  `update()`, `delete()`, `copy()` und `move()` sind Schreibvorgänge: Sie erhalten **einen einzigen Versuch** und werden nie wiederholt. Siehe [Wiederholungsrichtlinie](/de/sdks/blob/errors#wiederholungsrichtlinie).
</Note>