Client API: Object Storage: Migrations

Part of Object Storage.

GET /api/v1/client/object-storage/{service_id}/migrations

The service's migrations, newest first, with the provider presets a new one can use and the limits.

Each item has its status (queued, running, done, failed or cancelled), the source (provider, endpoint, region, source_bucket, source_prefix and the last four characters of its access key as access_key_hint), the destination (bucket_id, bucket_name, dest_prefix, overwrite) and its progress: objects_listed, objects_copied, objects_skipped (already in the destination), objects_failed, bytes_copied and last_key, the last source key it reached. listed_all turns true once the whole source has been listed, so objects_listed is the total from then on. A done migration with objects_failed above zero finished with failures, and can_retry says whether a retry has anything to do; failures_dropped counts the failed objects beyond the last 1000 we keep. error says why one failed.

providers lists each preset's endpoint (with {region}, or null when you give the endpoint) and whether it needs a region. limits.running_max is how many may be queued or running at once.

Answers 404 for a service that is not this account's Object Storage.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/object-storage/{service_id}/migrations

Start copying objects from another provider into one of the service's buckets. We check the source first, as the preflight does, and the copy starts within a minute. It runs in the background until every object under the prefix is copied; the migration's status and counts show how far it got.

Each object keeps its Content-Type, Cache-Control, Content-Disposition, Content-Encoding, Content-Language and user metadata. The destination key is dest_prefix followed by the source key. We keep the keys encrypted while the migration runs and delete them when it ends. Copies are free; the storage they take is billed as storage.

Answers the migration as GET writes it. Answers 404 for a service or bucket that is not this account's, 409 when the service is not active or already has 3 migrations queued or running, 422 or 502 as the preflight does, and 429 after 30 migration changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/client/object-storage/{service_id}/migrations/preflight

Check a source before a migration starts: we list the bucket (under the prefix) with the key and read the first object's headers. Nothing is copied and nothing is stored.

Answers {"ok": true, "endpoint", "region", "bucket", "prefix", "sample", "more"}: sample is up to five of the objects found, and more is true when there are others. Answers 422 with the reason when the source refuses the key, has no such bucket, is in another region, or the endpoint is not a public HTTPS endpoint; 502 when the source cannot be reached or answers with an error of its own; 404 for a service that is not this account's Object Storage; 429 after 30 checks in ten minutes.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/client/object-storage/{service_id}/migrations/{migration_id}

One migration, as the list writes it. Answers 404 for a service or a migration that is not this account's.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/object-storage/{service_id}/migrations/{migration_id}/cancel

Stop a queued or running migration and delete its source keys. Objects it already copied stay in the bucket, and a large object it was copying part by part is discarded. Works whatever the service's status, so a suspended service can still stop one.

Answers the migration, now cancelled. Answers 404 for a migration that is not this account's, 409 when it has already ended, and 429 after 30 migration changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/client/object-storage/{service_id}/migrations/{migration_id}/failures

The objects a migration could not copy, most recent first: each one's key, size (null when the source did not say), the error, how many attempts were made, and retry_pending while a retry has yet to reach it. We keep the last 1000 (kept_max); total is how many are kept now.

Answers 404 for a migration that is not this account's.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/client/object-storage/{service_id}/migrations/{migration_id}/retry

Try a migration again: first the objects it could not copy, then the rest of the source from where it stopped. We delete the source keys when a migration ends, so send them again; we check them as the preflight does.

For a migration that failed, or one that is done with failures. When more objects failed than the last 1000 we keep, the retry walks the whole source again and skips what the bucket already holds.

Answers the migration, queued again. Answers 404 for a migration that is not this account's, 409 when the service is not active, when it has nothing to try again or when 3 migrations are already queued or running, 422 or 502 as the preflight does, and 429 after 30 migration changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)