googleapis/swift-google-cloud-storage

Overview

This library implements types to work with Google Cloud Storage.

Use StorageClient to write (upload) and read (download) [objects]. A default initialized StorageClient works in most cases. The client supports resumable uploads, single-shot uploads, full and partial object reads. To provide data for writes implement the SeekableWriteObjectSource or the WriteObjectSource protocols.

Use StorageControlClient for other operations, including listing, deleting, updating object metadata, object rewrites, and object composition. The same type can be used to perform all operations on [buckets].

Use StorageProtocol and StorageControlProtocol if you want to mock the clients in your tests.

[buckets]: https://docs.cloud.google.com/storage/docs/buckets [objects]: https://docs.cloud.google.com/storage/docs/objects

Quickstart

The following example demonstrates using StorageControlClient:

import GoogleCloudStorage

public func quickstart(
  client: StorageControlClient, projectId: String, bucketId: String
) async throws {
  let bucket =
    try await client
    .createBucket(
      request: .init().with {
        $0.parent = "projects/_"
        $0.bucketId = bucketId
        $0.bucket = .init().with { bucket in
          bucket.project = "projects/\(projectId)"
          bucket.storageClass = "STANDARD"
          bucket.location = "US"
        }
      })
  print("successfully created bucket \(bucket)")
}

Requirements

For the minimum supported Swift version and platform requirements, see the Requirements section in the google-cloud-swift repository.

Installation

Add swift-google-cloud-storage as a package dependency:

swift package add-dependency https://github.com/googleapis/swift-google-cloud-storage.git --from 0.3.0

Then add GoogleCloudStorage to your target's dependencies:

swift package add-target-dependency GoogleCloudStorage <target-name> --package swift-google-cloud-storage

Troubleshooting

Object download (readObject) and upload (writeObject) operations throw ReadObjectError and WriteObjectError respectively, while control-plane operations on StorageControlClient throw RequestError.

For detailed guidance on handling checksum mismatches, resuming interrupted downloads and uploads, choosing between SeekableWriteObjectSource and WriteObjectSource, and using preconditions for idempotent retries, see the Troubleshooting Guide.

For questions, bug reports, or feature requests, please open an issue in the google-cloud-swift repository.

Contributing

Contributions to this library are always welcome and highly encouraged.

All development, issues, and pull requests are managed in the google-cloud-swift monorepo. See CONTRIBUTING.md for details on getting started.

License

Apache 2.0 - See LICENSE for more information.

Package Metadata

Repository: googleapis/swift-google-cloud-storage

Default branch: main

README: README.md