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 ¶
- func CreateTempURL(c *gophercloud.ServiceClient, containerName, objectName string, ...) (string, error)
- func ExtractNames(r pagination.Page) ([]string, error)
- func List(c *gophercloud.ServiceClient, containerName string, opts ListOptsBuilder) pagination.Pager
- type BulkDeleteResponse
- type BulkDeleteResult
- type CopyHeader
- type CopyOpts
- type CopyOptsBuilder
- type CopyResult
- type CreateHeader
- type CreateOpts
- type CreateOptsBuilder
- type CreateResult
- type CreateTempURLOpts
- type DeleteHeader
- type DeleteOpts
- type DeleteOptsBuilder
- type DeleteResult
- type DownloadHeader
- type DownloadOpts
- type DownloadOptsBuilder
- type DownloadResult
- type ErrWrongChecksum
- type GetHeader
- type GetOpts
- type GetOptsBuilder
- type GetResult
- type HTTPMethod
- type ListOpts
- type ListOptsBuilder
- type Object
- type ObjectPage
- type UpdateHeader
- type UpdateOpts
- type UpdateOptsBuilder
- type UpdateResult
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 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.
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"` }
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"` }
CopyOpts is a structure that holds parameters for copying one object to another.
type CopyOptsBuilder ¶
CopyOptsBuilder allows extensions to add additional 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"` }
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 ¶
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" and "POST". 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 // Timestamp is a timestamp to calculate Temp URL signature. Optional. Timestamp time.Time }
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"` }
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"`
}
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 ¶
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"` }
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"` }
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 ¶
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, pass the DownloadResult response to the ExtractContent function.
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 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"` }
GetHeader represents the headers returned in the response from a Get request.
func (*GetHeader) UnmarshalJSON ¶
type GetOpts ¶
type GetOpts struct { Newest bool `h:"X-Newest"` Expires string `q:"expires"` Signature string `q:"signature"` }
GetOpts is a structure that holds parameters for getting an object's metadata.
type GetOptsBuilder ¶
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.
type HTTPMethod ¶
type HTTPMethod string
HTTPMethod represents an HTTP method string (e.g. "GET").
var ( // GET represents an HTTP "GET" method. GET HTTPMethod = "GET" // POST represents an HTTP "POST" method. POST HTTPMethod = "POST" )
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"` }
ListOpts is a structure that holds parameters for listing objects.
type ListOptsBuilder ¶
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"` }
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 ¶
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"` }
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 ¶
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.