objects

package
v1.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2024 License: Apache-2.0 Imports: 18 Imported by: 198

Documentation

Overview

Package objects contains functionality for working with Object Storage object resources. An object is a resource that represents and contains data - such as documents, images, and so on. You can also store custom metadata with an object.

Note: When referencing the Object Storage API docs, some of the API actions are listed under "containers" rather than "objects". This was an intentional design in Gophercloud to make some object actions feel more natural.

Example to List Objects 

containerName := "my_container"

listOpts := objects.ListOpts{
	Full: true,
}

allPages, err := objects.List(objectStorageClient, containerName, listOpts).AllPages()
if err != nil {
	panic(err)
}

allObjects, err := objects.ExtractInfo(allPages)
if err != nil {
	panic(err)
}

for _, object := range allObjects {
	fmt.Printf("%+v\n", object)
}

Example to List Object Names 

containerName := "my_container"

listOpts := objects.ListOpts{
	Full: false,
}

allPages, err := objects.List(objectStorageClient, containerName, listOpts).AllPages()
if err != nil {
	panic(err)
}

allObjects, err := objects.ExtractNames(allPages)
if err != nil {
	panic(err)
}

for _, object := range allObjects {
	fmt.Printf("%+v\n", object)
}

Example to Create an Object 

content := "some object content"
objectName := "my_object"
containerName := "my_container"

createOpts := objects.CreateOpts{
	ContentType: "text/plain"
	Content:     strings.NewReader(content),
}

object, err := objects.Create(objectStorageClient, containerName, objectName, createOpts).Extract()
if err != nil {
	panic(err)
}

Example to Copy an Object 

objectName := "my_object"
containerName := "my_container"

copyOpts := objects.CopyOpts{
	Destination: "/newContainer/newObject",
}

object, err := objects.Copy(objectStorageClient, containerName, objectName, copyOpts).Extract()
if err != nil {
	panic(err)
}

Example to Delete an Object 

objectName := "my_object"
containerName := "my_container"

object, err := objects.Delete(objectStorageClient, containerName, objectName).Extract()
if err != nil {
	panic(err)
}

Example to Download an Object's Data 

objectName := "my_object"
containerName := "my_container"

object := objects.Download(objectStorageClient, containerName, objectName, nil)
if object.Err != nil {
	panic(object.Err)
}
// if "ExtractContent" method is not called, the HTTP connection will remain consumed
content, err := object.ExtractContent()
if err != nil {
	panic(err)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateTempURL 

func CreateTempURL(c *gophercloud.ServiceClient, containerName, objectName string, opts CreateTempURLOpts) (string, error)

CreateTempURL is a function for creating a temporary URL for an object. It allows users to have "GET" or "POST" access to a particular tenant's object for a limited amount of time.

func ExtractNames 

func ExtractNames(r pagination.Page) ([]string, error)

ExtractNames is a function that takes a page of objects and returns only their names.

func List 

func List(c *gophercloud.ServiceClient, containerName string, opts ListOptsBuilder) pagination.Pager

List is a function that retrieves all objects in a container. It also returns the details for the container. To extract only the object information or names, pass the ListResult response to the ExtractInfo or ExtractNames function, respectively.

Types

type BulkDeleteResponse added in v0.11.0 

type BulkDeleteResponse struct {
	ResponseStatus string     `json:"Response Status"`
	ResponseBody   string     `json:"Response Body"`
	Errors         [][]string `json:"Errors"`
	NumberDeleted  int        `json:"Number Deleted"`
	NumberNotFound int        `json:"Number Not Found"`
}

type BulkDeleteResult added in v0.11.0 

type BulkDeleteResult struct {
	gophercloud.Result
}

BulkDeleteResult represents the result of a bulk delete operation. To extract the response object from the HTTP response, call its Extract method.

func BulkDelete added in v0.11.0 

func BulkDelete(c *gophercloud.ServiceClient, container string, objects []string) (r BulkDeleteResult)

BulkDelete is a function that bulk deletes objects. In Swift, the maximum number of deletes per request is set by default to 10000.

See: * https://github.com/openstack/swift/blob/6d3d4197151f44bf28b51257c1a4c5d33411dcae/etc/proxy-server.conf-sample#L1029-L1034 * https://github.com/openstack/swift/blob/e8cecf7fcc1630ee83b08f9a73e1e59c07f8d372/swift/common/middleware/bulk.py#L309

func (BulkDeleteResult) Extract added in v0.11.0 

func (r BulkDeleteResult) Extract() (*BulkDeleteResponse, error)

Extract will return a BulkDeleteResponse struct returned from a BulkDelete call.

type CopyHeader 

type CopyHeader struct {
	ContentLength          int64     `json:"Content-Length,string"`
	ContentType            string    `json:"Content-Type"`
	CopiedFrom             string    `json:"X-Copied-From"`
	CopiedFromLastModified time.Time `json:"-"`
	Date                   time.Time `json:"-"`
	ETag                   string    `json:"Etag"`
	LastModified           time.Time `json:"-"`
	TransID                string    `json:"X-Trans-Id"`
	ObjectVersionID        string    `json:"X-Object-Version-Id"`
}

CopyHeader represents the headers returned in the response from a Copy request.

func (*CopyHeader) UnmarshalJSON 

func (r *CopyHeader) UnmarshalJSON(b []byte) error

type CopyOpts 

type CopyOpts struct {
	Metadata           map[string]string
	ContentDisposition string `h:"Content-Disposition"`
	ContentEncoding    string `h:"Content-Encoding"`
	ContentType        string `h:"Content-Type"`
	Destination        string `h:"Destination" required:"true"`
	ObjectVersionID    string `q:"version-id"`
}

CopyOpts is a structure that holds parameters for copying one object to another.

func (CopyOpts) ToObjectCopyMap 

func (opts CopyOpts) ToObjectCopyMap() (map[string]string, error)

ToObjectCopyMap formats a CopyOpts into a map of headers.

func (CopyOpts) ToObjectCopyQuery added in v1.3.0 

func (opts CopyOpts) ToObjectCopyQuery() (string, error)

ToObjectCopyQuery formats a CopyOpts into a query.

type CopyOptsBuilder 

type CopyOptsBuilder interface {
	ToObjectCopyMap() (map[string]string, error)
}

CopyOptsBuilder allows extensions to add additional parameters to the Copy request.

type CopyOptsQueryBuilder added in v1.3.0 

type CopyOptsQueryBuilder interface {
	ToObjectCopyQuery() (string, error)
}

CopyOptsQueryBuilder allows extensions to add additional query parameters to the Copy request.

type CopyResult 

type CopyResult struct {
	gophercloud.HeaderResult
}

CopyResult represents the result of a copy operation.

func Copy 

func Copy(c *gophercloud.ServiceClient, containerName, objectName string, opts CopyOptsBuilder) (r CopyResult)

Copy is a function that copies one object to another.

func (CopyResult) Extract 

func (r CopyResult) Extract() (*CopyHeader, error)

Extract will return a struct of headers returned from a call to Copy.

type CreateHeader 

type CreateHeader struct {
	ContentLength   int64     `json:"Content-Length,string"`
	ContentType     string    `json:"Content-Type"`
	Date            time.Time `json:"-"`
	ETag            string    `json:"Etag"`
	LastModified    time.Time `json:"-"`
	TransID         string    `json:"X-Trans-Id"`
	ObjectVersionID string    `json:"X-Object-Version-Id"`
}

CreateHeader represents the headers returned in the response from a Create request.

func (*CreateHeader) UnmarshalJSON 

func (r *CreateHeader) UnmarshalJSON(b []byte) error

type CreateOpts 

type CreateOpts struct {
	Content            io.Reader
	Metadata           map[string]string
	NoETag             bool
	CacheControl       string `h:"Cache-Control"`
	ContentDisposition string `h:"Content-Disposition"`
	ContentEncoding    string `h:"Content-Encoding"`
	ContentLength      int64  `h:"Content-Length"`
	ContentType        string `h:"Content-Type"`
	CopyFrom           string `h:"X-Copy-From"`
	DeleteAfter        int64  `h:"X-Delete-After"`
	DeleteAt           int64  `h:"X-Delete-At"`
	DetectContentType  string `h:"X-Detect-Content-Type"`
	ETag               string `h:"ETag"`
	IfNoneMatch        string `h:"If-None-Match"`
	ObjectManifest     string `h:"X-Object-Manifest"`
	TransferEncoding   string `h:"Transfer-Encoding"`
	Expires            string `q:"expires"`
	MultipartManifest  string `q:"multipart-manifest"`
	Signature          string `q:"signature"`
}

CreateOpts is a structure that holds parameters for creating an object.

func (CreateOpts) ToObjectCreateParams 

func (opts CreateOpts) ToObjectCreateParams() (io.Reader, map[string]string, string, error)

ToObjectCreateParams formats a CreateOpts into a query string and map of headers.

type CreateOptsBuilder 

type CreateOptsBuilder interface {
	ToObjectCreateParams() (io.Reader, map[string]string, string, error)
}

CreateOptsBuilder allows extensions to add additional parameters to the Create request.

type CreateResult 

type CreateResult struct {
	gophercloud.HeaderResult
	// contains filtered or unexported fields
}

CreateResult represents the result of a create operation.

func Create 

func Create(c *gophercloud.ServiceClient, containerName, objectName string, opts CreateOptsBuilder) (r CreateResult)

Create is a function that creates a new object or replaces an existing object. If the returned response's ETag header fails to match the local checksum, the failed request will automatically be retried up to a maximum of 3 times.

func (CreateResult) Extract 

func (r CreateResult) Extract() (*CreateHeader, error)

Extract will return a struct of headers returned from a call to Create.

type CreateTempURLOpts 

type CreateTempURLOpts struct {
	// (REQUIRED) Method is the HTTP method to allow for users of the temp URL.
	// Valid values are "GET", "HEAD", "PUT", "POST" and "DELETE".
	Method HTTPMethod

	// (REQUIRED) TTL is the number of seconds the temp URL should be active.
	TTL int

	// (Optional) Split is the string on which to split the object URL. Since only
	// the object path is used in the hash, the object URL needs to be parsed. If
	// empty, the default OpenStack URL split point will be used ("/v1/").
	Split string

	// (Optional) Timestamp is the current timestamp used to calculate the Temp URL
	// signature. If not specified, the current UNIX timestamp is used as the base
	// timestamp.
	Timestamp time.Time

	// (Optional) TempURLKey overrides the Swift container or account Temp URL key.
	// TempURLKey must correspond to a target container/account key, otherwise the
	// generated link will be invalid. If not specified, the key is obtained from
	// a Swift container or account.
	TempURLKey string

	// (Optional) Digest specifies the cryptographic hash function used to
	// calculate the signature. Valid values include sha1, sha256, and
	// sha512. If not specified, the default hash function is sha1.
	Digest string
}

CreateTempURLOpts are options for creating a temporary URL for an object.

type DeleteHeader 

type DeleteHeader struct {
	ContentLength          int64     `json:"Content-Length,string"`
	ContentType            string    `json:"Content-Type"`
	Date                   time.Time `json:"-"`
	TransID                string    `json:"X-Trans-Id"`
	ObjectVersionID        string    `json:"X-Object-Version-Id"`
	ObjectCurrentVersionID string    `json:"X-Object-Current-Version-Id"`
}

DeleteHeader represents the headers returned in the response from a Delete request.

func (*DeleteHeader) UnmarshalJSON 

func (r *DeleteHeader) UnmarshalJSON(b []byte) error

type DeleteOpts 

type DeleteOpts struct {
	MultipartManifest string `q:"multipart-manifest"`
	ObjectVersionID   string `q:"version-id"`
}

DeleteOpts is a structure that holds parameters for deleting an object.

func (DeleteOpts) ToObjectDeleteQuery 

func (opts DeleteOpts) ToObjectDeleteQuery() (string, error)

ToObjectDeleteQuery formats a DeleteOpts into a query string.

type DeleteOptsBuilder 

type DeleteOptsBuilder interface {
	ToObjectDeleteQuery() (string, error)
}

DeleteOptsBuilder allows extensions to add additional parameters to the Delete request.

type DeleteResult 

type DeleteResult struct {
	gophercloud.HeaderResult
}

DeleteResult represents the result of a delete operation.

func Delete 

func Delete(c *gophercloud.ServiceClient, containerName, objectName string, opts DeleteOptsBuilder) (r DeleteResult)

Delete is a function that deletes an object.

func (DeleteResult) Extract 

func (r DeleteResult) Extract() (*DeleteHeader, error)

Extract will return a struct of headers returned from a call to Delete.

type DownloadHeader 

type DownloadHeader struct {
	AcceptRanges       string    `json:"Accept-Ranges"`
	ContentDisposition string    `json:"Content-Disposition"`
	ContentEncoding    string    `json:"Content-Encoding"`
	ContentLength      int64     `json:"Content-Length,string"`
	ContentType        string    `json:"Content-Type"`
	Date               time.Time `json:"-"`
	DeleteAt           time.Time `json:"-"`
	ETag               string    `json:"Etag"`
	LastModified       time.Time `json:"-"`
	ObjectManifest     string    `json:"X-Object-Manifest"`
	StaticLargeObject  bool      `json:"-"`
	TransID            string    `json:"X-Trans-Id"`
	ObjectVersionID    string    `json:"X-Object-Version-Id"`
}

DownloadHeader represents the headers returned in the response from a Download request.

func (*DownloadHeader) UnmarshalJSON 

func (r *DownloadHeader) UnmarshalJSON(b []byte) error

type DownloadOpts 

type DownloadOpts struct {
	IfMatch           string    `h:"If-Match"`
	IfModifiedSince   time.Time `h:"If-Modified-Since"`
	IfNoneMatch       string    `h:"If-None-Match"`
	IfUnmodifiedSince time.Time `h:"If-Unmodified-Since"`
	Newest            bool      `h:"X-Newest"`
	Range             string    `h:"Range"`
	Expires           string    `q:"expires"`
	MultipartManifest string    `q:"multipart-manifest"`
	Signature         string    `q:"signature"`
	ObjectVersionID   string    `q:"version-id"`
}

DownloadOpts is a structure that holds parameters for downloading an object.

func (DownloadOpts) ToObjectDownloadParams 

func (opts DownloadOpts) ToObjectDownloadParams() (map[string]string, string, error)

ToObjectDownloadParams formats a DownloadOpts into a query string and map of headers.

type DownloadOptsBuilder 

type DownloadOptsBuilder interface {
	ToObjectDownloadParams() (map[string]string, string, error)
}

DownloadOptsBuilder allows extensions to add additional parameters to the Download request.

type DownloadResult 

type DownloadResult struct {
	gophercloud.HeaderResult
	Body io.ReadCloser
}

DownloadResult is a *http.Response that is returned from a call to the Download function.

func Download 

func Download(c *gophercloud.ServiceClient, containerName, objectName string, opts DownloadOptsBuilder) (r DownloadResult)

Download is a function that retrieves the content and metadata for an object. To extract just the content, call the DownloadResult method ExtractContent, after checking DownloadResult's Err field.

func (DownloadResult) Extract 

func (r DownloadResult) Extract() (*DownloadHeader, error)

Extract will return a struct of headers returned from a call to Download.

func (*DownloadResult) ExtractContent 

func (r *DownloadResult) ExtractContent() ([]byte, error)

ExtractContent is a function that takes a DownloadResult's io.Reader body and reads all available data into a slice of bytes. Please be aware that due the nature of io.Reader is forward-only - meaning that it can only be read once and not rewound. You can recreate a reader from the output of this function by using bytes.NewReader(downloadBytes)

type ErrTempURLDigestNotValid added in v1.4.0 

type ErrTempURLDigestNotValid struct {
	gophercloud.ErrMissingInput
	Digest string
}

ErrTempURLDigestNotValid is an error indicating that the requested cryptographic hash function is not supported.

func (ErrTempURLDigestNotValid) Error added in v1.4.0 

func (e ErrTempURLDigestNotValid) Error() string

type ErrTempURLKeyNotFound added in v1.4.0 

type ErrTempURLKeyNotFound struct{ gophercloud.ErrMissingInput }

ErrTempURLKeyNotFound is an error indicating that the Temp URL key was neigther set nor resolved from a container or account metadata.

func (ErrTempURLKeyNotFound) Error added in v1.4.0 

func (e ErrTempURLKeyNotFound) Error() string

type ErrWrongChecksum 

type ErrWrongChecksum struct {
	gophercloud.BaseError
}

ErrWrongChecksum is the error when the checksum generated for an object doesn't match the ETAG header.

func (ErrWrongChecksum) Error 

func (e ErrWrongChecksum) Error() string

type GetHeader 

type GetHeader struct {
	ContentDisposition string    `json:"Content-Disposition"`
	ContentEncoding    string    `json:"Content-Encoding"`
	ContentLength      int64     `json:"Content-Length,string"`
	ContentType        string    `json:"Content-Type"`
	Date               time.Time `json:"-"`
	DeleteAt           time.Time `json:"-"`
	ETag               string    `json:"Etag"`
	LastModified       time.Time `json:"-"`
	ObjectManifest     string    `json:"X-Object-Manifest"`
	StaticLargeObject  bool      `json:"-"`
	TransID            string    `json:"X-Trans-Id"`
	ObjectVersionID    string    `json:"X-Object-Version-Id"`
}

GetHeader represents the headers returned in the response from a Get request.

func (*GetHeader) UnmarshalJSON 

func (r *GetHeader) UnmarshalJSON(b []byte) error

type GetOpts 

type GetOpts struct {
	Newest          bool   `h:"X-Newest"`
	Expires         string `q:"expires"`
	Signature       string `q:"signature"`
	ObjectVersionID string `q:"version-id"`
}

GetOpts is a structure that holds parameters for getting an object's metadata.

func (GetOpts) ToObjectGetParams 

func (opts GetOpts) ToObjectGetParams() (map[string]string, string, error)

ToObjectGetParams formats a GetOpts into a query string and a map of headers.

type GetOptsBuilder 

type GetOptsBuilder interface {
	ToObjectGetParams() (map[string]string, string, error)
}

GetOptsBuilder allows extensions to add additional parameters to the Get request.

type GetResult 

type GetResult struct {
	gophercloud.HeaderResult
}

GetResult is a *http.Response that is returned from a call to the Get function.

func Get 

func Get(c *gophercloud.ServiceClient, containerName, objectName string, opts GetOptsBuilder) (r GetResult)

Get is a function that retrieves the metadata of an object. To extract just the custom metadata, pass the GetResult response to the ExtractMetadata function.

func (GetResult) Extract 

func (r GetResult) Extract() (*GetHeader, error)

Extract will return a struct of headers returned from a call to Get.

func (GetResult) ExtractMetadata 

func (r GetResult) ExtractMetadata() (map[string]string, error)

ExtractMetadata is a function that takes a GetResult (of type *http.Response) and returns the custom metadata associated with the object.

type HTTPMethod 

type HTTPMethod string

HTTPMethod represents an HTTP method string (e.g. "GET"). 

var (
	// GET represents an HTTP "GET" method.
	GET HTTPMethod = "GET"
	// HEAD represents an HTTP "HEAD" method.
	HEAD HTTPMethod = "HEAD"
	// PUT represents an HTTP "PUT" method.
	PUT HTTPMethod = "PUT"
	// POST represents an HTTP "POST" method.
	POST HTTPMethod = "POST"
	// DELETE represents an HTTP "DELETE" method.
	DELETE HTTPMethod = "DELETE"
)

type ListOpts 

type ListOpts struct {
	// Full is a true/false value that represents the amount of object information
	// returned. If Full is set to true, then the content-type, number of bytes,
	// hash date last modified, and name are returned. If set to false or not set,
	// then only the object names are returned.
	Full      bool
	Limit     int    `q:"limit"`
	Marker    string `q:"marker"`
	EndMarker string `q:"end_marker"`
	Format    string `q:"format"`
	Prefix    string `q:"prefix"`
	Delimiter string `q:"delimiter"`
	Path      string `q:"path"`
	Versions  bool   `q:"versions"`
}

ListOpts is a structure that holds parameters for listing objects.

func (ListOpts) ToObjectListParams 

func (opts ListOpts) ToObjectListParams() (bool, string, error)

ToObjectListParams formats a ListOpts into a query string and boolean representing whether to list complete information for each object.

type ListOptsBuilder 

type ListOptsBuilder interface {
	ToObjectListParams() (bool, string, error)
}

ListOptsBuilder allows extensions to add additional parameters to the List request.

type Object 

type Object struct {
	// Bytes is the total number of bytes that comprise the object.
	Bytes int64 `json:"bytes"`

	// ContentType is the content type of the object.
	ContentType string `json:"content_type"`

	// Hash represents the MD5 checksum value of the object's content.
	Hash string `json:"hash"`

	// LastModified is the time the object was last modified.
	LastModified time.Time `json:"-"`

	// Name is the unique name for the object.
	Name string `json:"name"`

	// Subdir denotes if the result contains a subdir.
	Subdir string `json:"subdir"`

	// IsLatest indicates whether the object version is the latest one.
	IsLatest bool `json:"is_latest"`

	// VersionID contains a version ID of the object, when container
	// versioning is enabled.
	VersionID string `json:"version_id"`
}

Object is a structure that holds information related to a storage object.

func ExtractInfo 

func ExtractInfo(r pagination.Page) ([]Object, error)

ExtractInfo is a function that takes a page of objects and returns their full information.

func (*Object) UnmarshalJSON 

func (r *Object) UnmarshalJSON(b []byte) error

type ObjectPage 

type ObjectPage struct {
	pagination.MarkerPageBase
}

ObjectPage is a single page of objects that is returned from a call to the List function.

func (ObjectPage) IsEmpty 

func (r ObjectPage) IsEmpty() (bool, error)

IsEmpty returns true if a ListResult contains no object names.

func (ObjectPage) LastMarker 

func (r ObjectPage) LastMarker() (string, error)

LastMarker returns the last object name in a ListResult.

type UpdateHeader 

type UpdateHeader struct {
	ContentLength   int64     `json:"Content-Length,string"`
	ContentType     string    `json:"Content-Type"`
	Date            time.Time `json:"-"`
	TransID         string    `json:"X-Trans-Id"`
	ObjectVersionID string    `json:"X-Object-Version-Id"`
}

UpdateHeader represents the headers returned in the response from a Update request.

func (*UpdateHeader) UnmarshalJSON 

func (r *UpdateHeader) UnmarshalJSON(b []byte) error

type UpdateOpts 

type UpdateOpts struct {
	Metadata           map[string]string
	RemoveMetadata     []string
	ContentDisposition *string `h:"Content-Disposition"`
	ContentEncoding    *string `h:"Content-Encoding"`
	ContentType        *string `h:"Content-Type"`
	DeleteAfter        *int64  `h:"X-Delete-After"`
	DeleteAt           *int64  `h:"X-Delete-At"`
	DetectContentType  *bool   `h:"X-Detect-Content-Type"`
}

UpdateOpts is a structure that holds parameters for updating, creating, or deleting an object's metadata.

func (UpdateOpts) ToObjectUpdateMap 

func (opts UpdateOpts) ToObjectUpdateMap() (map[string]string, error)

ToObjectUpdateMap formats a UpdateOpts into a map of headers.

type UpdateOptsBuilder 

type UpdateOptsBuilder interface {
	ToObjectUpdateMap() (map[string]string, error)
}

UpdateOptsBuilder allows extensions to add additional parameters to the Update request.

type UpdateResult 

type UpdateResult struct {
	gophercloud.HeaderResult
}

UpdateResult represents the result of an update operation.

func Update 

func Update(c *gophercloud.ServiceClient, containerName, objectName string, opts UpdateOptsBuilder) (r UpdateResult)

Update is a function that creates, updates, or deletes an object's metadata.

func (UpdateResult) Extract 

func (r UpdateResult) Extract() (*UpdateHeader, error)

Extract will return a struct of headers returned from a call to Update.

Source Files

View all Source files

Directories

Path Synopsis
objects unit tests
 objects unit tests

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.