transloadit

package module
v1.5.2 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2024 License: MIT Imports: 18 Imported by: 11

README

go-sdk

A Go Integration for Transloadit's file uploading and encoding service

Intro

Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.

This is a Go SDK to make it easy to talk to the Transloadit REST API.

Install

go get github.com/transloadit/go-sdk

The Go SDK is confirmed to work with Go 1.11 or higher.

Usage

package main

import (
	"context"
	"fmt"

	"github.com/transloadit/go-sdk"
)

func main() {
	// Create client
	options := transloadit.DefaultConfig
	options.AuthKey = "YOUR_TRANSLOADIT_KEY"
	options.AuthSecret = "YOUR_TRANSLOADIT_SECRET"
	client := transloadit.NewClient(options)

	// Initialize new assembly
	assembly := transloadit.NewAssembly()

	// Add a file to upload
	assembly.AddFile("image", "/PATH/TO/FILE.jpg")

	// Add Instructions, e.g. resize image to 75x75px
	assembly.AddStep("resize", map[string]interface{}{
		"robot":           "/image/resize",
		"width":           75,
		"height":          75,
		"resize_strategy": "pad",
		"background":      "#000000",
	})

	// Start the upload
	info, err := client.StartAssembly(context.Background(), assembly)
	if err != nil {
		panic(err)
	}

	// All files have now been uploaded and the assembly has started but no
	// results are available yet since the conversion has not finished.
	// WaitForAssembly provides functionality for polling until the assembly
	// has ended.
	info, err = client.WaitForAssembly(context.Background(), info)
	if err != nil {
		panic(err)
	}

	fmt.Printf("You can view the result at: %s\n", info.Results["resize"][0].SSLURL)
}

Example

For fully working examples on how to use templates, non-blocking processing and more, take a look at examples/.

Documentation

See Godoc for full API documentation.

License

MIT Licensed

Documentation

Overview

Package transloadit provides a client to interact with the Transloadt API.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultConfig = Config{
	Endpoint: "https://api2.transloadit.com",
}

DefaultConfig is the recommended base configuration.

View Source 
var Version = "v1.5.2"

Version specifies the version of the Go SDK.

Functions

This section is empty.

Types

type Assembly 

type Assembly struct {
	// NotifiyURL specifies a URL to which a request will be sent once the
	// assembly finishes.
	// See https://transloadit.com/docs#notifications
	NotifyURL string
	// TemplateID specifies a optional template from which the encoding
	// instructions will be fetched.
	// See https://transloadit.com/docs/topics/templates/
	TemplateID string
	// Fields specifies additional key-value pairs that can be accessed by
	// Assembly Instructions to allow customizing steps on a per-assembly basis.
	// See https://transloadit.com/docs/topics/assembly-instructions/#assembly-variables
	Fields map[string]interface{}
	// contains filtered or unexported fields
}

Assembly contains instructions used for starting assemblies.

func NewAssembly added in v1.0.0 

func NewAssembly() Assembly

NewAssembly will create a new Assembly struct which can be used to start an assembly using Client.StartAssembly.

func (*Assembly) AddFile added in v0.1.9 

func (assembly *Assembly) AddFile(fieldname, filepath string) error

AddFile will open the provided file path and add it to the list which will be uploaded once Client.StartAssembly is invoked. The corresponding field name can be used to reference the file in the assembly instructions.

func (*Assembly) AddReader 

func (assembly *Assembly) AddReader(fieldname, filename string, reader io.ReadCloser)

AddReader will add the provided io.Reader to the list which will be uploaded once Client.StartAssembly is invoked. The corresponding field name can be used to reference the file in the assembly instructions.

func (*Assembly) AddStep 

func (assembly *Assembly) AddStep(name string, details map[string]interface{})

AddStep will add the provided step to the assembly instructions. Details about possible values can be found at https://transloadit.com/docs/topics/assembly-instructions/

type AssemblyInfo 

type AssemblyInfo struct {
	Ok      string `json:"ok"`
	Error   string `json:"error"`
	Message string `json:"message"`

	AssemblyID             string                 `json:"assembly_id"`
	ParentID               string                 `json:"parent_id"`
	AssemblyURL            string                 `json:"assembly_url"`
	AssemblySSLURL         string                 `json:"assembly_ssl_url"`
	BytesReceived          int                    `json:"bytes_received"`
	BytesExpected          Integer                `json:"bytes_expected"`
	StartDate              string                 `json:"start_date"`
	IsInfinite             bool                   `json:"is_infinite"`
	HasDupeJobs            bool                   `json:"has_dupe_jobs"`
	UploadDuration         float32                `json:"upload_duration"`
	NotifyURL              string                 `json:"notify_url"`
	NotifyStart            string                 `json:"notify_start"`
	NotifyStatus           string                 `json:"notify_status"`
	NotifyDuation          float32                `json:"notify_duration"`
	LastJobCompleted       string                 `json:"last_job_completed"`
	ExecutionDuration      float32                `json:"execution_duration"`
	ExecutionStart         string                 `json:"execution_start"`
	Created                string                 `json:"created"`
	Files                  string                 `json:"files"`
	Fields                 map[string]interface{} `json:"fields"`
	BytesUsage             int                    `json:"bytes_usage"`
	FilesToStoreOnS3       int                    `json:"files_to_store_on_s3"`
	QueuedFilesToStoreOnS3 int                    `json:"queued_files_to_store_on_s3"`
	ExecutingJobs          []string               `json:"executing_jobs"`
	StartedJobs            []string               `json:"started_jobs"`
	ParentAssemblyStatus   *AssemblyInfo          `json:"parent_assembly_status"`
	Uploads                []*FileInfo            `json:"uploads"`
	Results                map[string][]*FileInfo `json:"results"`
	Params                 string                 `json:"params"`

	// Since 7 March 2018, the user agent, IP and referer are no longer
	// stored by Transloadit (see https://transloadit.com/blog/2018/03/gdpr/)
	// Therefore, these properties will always hold empty strings.
	ClientAgent   string
	ClientIp      string
	ClientReferer string
}

AssemblyInfo contains details about an assemblies current status. Details about each value can be found at https://transloadit.com/docs/api-docs/#assembly-status-response

type AssemblyList 

type AssemblyList struct {
	Assemblies []*AssemblyListItem `json:"items"`
	Count      int                 `json:"count"`
}

AssemblyList contains a list of assemblies.

type AssemblyListItem 

type AssemblyListItem struct {
	Ok    string `json:"ok"`
	Error string `json:"error"`

	AssemblyID        string     `json:"id"`
	AccountID         string     `json:"account_id"`
	TemplateID        string     `json:"template_id"`
	Instance          string     `json:"instance"`
	NotifyURL         string     `json:"notify_url"`
	RedirectURL       string     `json:"redirect_url"`
	ExecutionDuration float32    `json:"execution_duration"`
	ExecutionStart    *time.Time `json:"execution_start"`
	Created           time.Time  `json:"created"`
	Files             string     `json:"files"`
}

AssemblyListItem contains reduced details about an assembly.

type AssemblyReplay 

type AssemblyReplay struct {
	// NotifiyURL specifies a URL to which a request will be sent once the
	// assembly finishes. This overwrites the notify url from the original
	// assembly instructions.
	// See https://transloadit.com/docs#notifications.
	NotifyURL string
	// ReparseTemplate specifies whether the template should be fetched again
	// before the assembly is replayed. This can be used if the template has
	// changed since the original assembly was created.
	ReparseTemplate bool
	// contains filtered or unexported fields
}

AssemblyReplay contains instructions used for replaying assemblies.

func NewAssemblyReplay added in v1.0.0 

func NewAssemblyReplay(assemblyURL string) AssemblyReplay

NewAssemblyReplay will create a new AssemblyReplay struct which can be used to replay an assemblie's execution using Client.StartAssemblyReplay. The assembly URL must be absolute, for example: https://api2-amberly.transloadit.com/assemblies/15a6b3701d3811e78d7bfba4db1b053e

func (*AssemblyReplay) AddStep 

func (assembly *AssemblyReplay) AddStep(name string, details map[string]interface{})

AddStep will add the provided step to the new assembly instructions. When the assembly is replayed, those new steps will be used instead of the original ones. Details about possible values can be found at https://transloadit.com/docs/topics/assembly-instructions/.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides an interface to the Transloadit REST API bound to a specific account.

func NewClient 

func NewClient(config Config) Client

NewClient creates a new client using the provided configuration struct. It will panic if no Config.AuthKey or Config.AuthSecret are empty.

func (*Client) CancelAssembly 

func (client *Client) CancelAssembly(ctx context.Context, assemblyURL string) (*AssemblyInfo, error)

CancelAssembly cancels an assembly which will result in all corresponding uploads and encoding jobs to be aborted. Finally, the updated assembly information after the cancellation will be returned. The assembly URL must be absolute, for example: https://api2-amberly.transloadit.com/assemblies/15a6b3701d3811e78d7bfba4db1b053e

func (*Client) CreateTemplate 

func (client *Client) CreateTemplate(ctx context.Context, template Template) (string, error)

CreateTemplate will save the provided template struct as a new template and return the ID of the new template.

func (*Client) CreateTemplateCredential added in v1.5.0 

func (client *Client) CreateTemplateCredential(ctx context.Context, templateCredential TemplateCredential) (string, error)

CreateTemplateCredential will save the provided template credential struct to the server and return the ID of the new template credential.

func (*Client) DeleteTemplate 

func (client *Client) DeleteTemplate(ctx context.Context, templateID string) error

DeleteTemplate will delete the template associated with the provided template ID.

func (*Client) DeleteTemplateCredential added in v1.5.0 

func (client *Client) DeleteTemplateCredential(ctx context.Context, templateCredentialID string) error

DeleteTemplateCredential will delete the template credential associated with the provided template ID.

func (*Client) GetAssembly 

func (client *Client) GetAssembly(ctx context.Context, assemblyURL string) (*AssemblyInfo, error)

GetAssembly fetches the full assembly status from the provided URL. The assembly URL must be absolute, for example: https://api2-amberly.transloadit.com/assemblies/15a6b3701d3811e78d7bfba4db1b053e

func (*Client) GetTemplate 

func (client *Client) GetTemplate(ctx context.Context, templateID string) (template Template, err error)

GetTemplate will retrieve details about the template associated with the provided template ID.

func (*Client) GetTemplateCredential added in v1.5.0 

func (client *Client) GetTemplateCredential(ctx context.Context, templateCredentialID string) (TemplateCredential, error)

GetTemplateCredential will retrieve details about the template credential associated with the provided template credential ID.

func (*Client) ListAssemblies 

func (client *Client) ListAssemblies(ctx context.Context, options *ListOptions) (AssemblyList, error)

ListAssemblies will fetch all assemblies matching the provided criteria.

func (*Client) ListNotifications deprecated 

func (client *Client) ListNotifications(ctx context.Context, options *ListOptions) (list NotificationList, err error)

ListNotifications will return a list containing all notifications matching the criteria defined using the ListOptions structure.

Deprecated: As of December 2021, the List Notifications API endpoint from Transloadit has been removed. This function will now always return an error.

func (*Client) ListTemplateCredential added in v1.5.0 

func (client *Client) ListTemplateCredential(ctx context.Context, options *ListOptions) (list TemplateCredentialList, err error)

ListTemplateCredential will retrieve all templates credential matching the criteria.

func (*Client) ListTemplates 

func (client *Client) ListTemplates(ctx context.Context, options *ListOptions) (list TemplateList, err error)

ListTemplates will retrieve all templates matching the criteria.

func (*Client) ReplayNotification 

func (client *Client) ReplayNotification(ctx context.Context, assemblyID string, notifyURL string) error

ReplayNotification instructs the endpoint to replay the notification corresponding to the provided assembly ID. If notifyURL is not empty it will override the notify URL used in the assembly instructions.

func (*Client) StartAssembly added in v1.0.0 

func (client *Client) StartAssembly(ctx context.Context, assembly Assembly) (*AssemblyInfo, error)

StartAssembly will upload all provided files and instruct the endpoint to start executing it. The function will return after all uploads complete and the remote server received the instructions (or the provided context times out). It won't wait until the execution has finished and results are available, which can be achieved using WaitForAssembly.

When an error is returned you should also check AssemblyInfo.Error for more information about the error sent by the Transloadit API: 

info, err := assembly.Upload()
if err != nil {
	if info != nil && info.Error != "" {
		// See info.Error
	}
	panic(err)
}

func (*Client) StartAssemblyReplay added in v1.0.0 

func (client *Client) StartAssemblyReplay(ctx context.Context, assembly AssemblyReplay) (*AssemblyInfo, error)

StartAssemblyReplay will instruct the endpoint to replay the entire assembly execution.

func (*Client) UpdateTemplate added in v1.0.0 

func (client *Client) UpdateTemplate(ctx context.Context, templateID string, newTemplate Template) error

UpdateTemplate will update the template associated with the provided template ID to match the new name and new content. Please be aware that you are not able to change a template's ID.

func (*Client) UpdateTemplateCredential added in v1.5.1 

func (client *Client) UpdateTemplateCredential(ctx context.Context, templateCredentialID string, templateCredential TemplateCredential) error

UpdateTemplateCredential will update the template credential associated with the provided template credential ID to match the new name and new content.

func (*Client) WaitForAssembly 

func (client *Client) WaitForAssembly(ctx context.Context, assembly *AssemblyInfo) (*AssemblyInfo, error)

WaitForAssembly fetches continuously the assembly status until it has finished uploading and executing or until an assembly error occurs. If you want to end this loop prematurely, you can cancel the supplied context.

type Config 

type Config struct {
	AuthKey    string
	AuthSecret string
	Endpoint   string
}

Config defines the configuration options for a client.

type FileInfo 

type FileInfo struct {
	ID               string                 `json:"id"`
	Name             string                 `json:"name"`
	Basename         string                 `json:"basename"`
	Ext              string                 `json:"ext"`
	Size             int                    `json:"size"`
	Mime             string                 `json:"mime"`
	Type             string                 `json:"type"`
	Field            string                 `json:"field"`
	Md5Hash          string                 `json:"md5hash"`
	OriginalMd5Hash  string                 `json:"original_md5hash"`
	OriginalID       string                 `json:"original_id"`
	OriginalBasename string                 `json:"original_basename"`
	URL              string                 `json:"url"`
	SSLURL           string                 `json:"ssl_url"`
	Meta             map[string]interface{} `json:"meta"`
}

FileInfo contains details about a file which was either uploaded or is the result of an executed assembly.

type Integer added in v1.4.1 

type Integer int

Integer is a warpper around a normal int but has softer JSON parsing requirements. It can be used in situations where a JSON value is not always a number. Then parsing will not fail and a default value of 0 will be returned. For more details see: https://github.com/transloadit/go-sdk/issues/26

func (*Integer) UnmarshalJSON added in v1.4.1 

func (i *Integer) UnmarshalJSON(text []byte) error

type ListOptions 

type ListOptions struct {
	Page       int        `json:"page,omitempty"`
	PageSize   int        `json:"pagesize,omitempty"`
	Sort       string     `json:"sort,omitempty"`
	Order      string     `json:"order,omitempty"`
	Fields     []string   `json:"fields,omitempty"`
	Type       string     `json:"type,omitempty"`
	Keywords   []string   `json:"keyword,omitempty"`
	AssemblyID string     `json:"assembly_id,omitempty"`
	FromDate   *time.Time `json:"fromdate,omitempty"`
	ToDate     *time.Time `json:"todate,omitempty"`
}

ListOptions defines criteria used when a list is being retrieved. Details about each property can be found at https://transloadit.com/docs/api-docs#retrieve-assembly-list.

type Notification added in v1.0.0 

type Notification struct {
	ID           string    `json:"id"`
	AssemblyID   string    `json:"assembly_id"`
	AccountID    string    `json:"account_id"`
	URL          string    `json:"url"`
	ResponseCode int       `json:"response_code"`
	ResponseData string    `json:"response_data"`
	Duration     float32   `json:"duration"`
	Created      time.Time `json:"created"`
	Error        string    `json:"error"`
}

Notification contains details about a notification.

type NotificationList 

type NotificationList struct {
	Notifications []Notification `json:"items"`
	Count         int            `json:"count"`
}

NotificationList contains a list of notifications.

type RequestError added in v1.0.0 

type RequestError struct {
	Code    string `json:"error"`
	Message string `json:"message"`
}

RequestError represents an error returned by the Transloadit API alongside additional service-specific information.

func (RequestError) Error added in v1.0.0 

func (err RequestError) Error() string

Error return a formatted message describing the error.

type Template 

type Template struct {
	ID                   string
	Name                 string
	Content              TemplateContent
	RequireSignatureAuth bool
}

Template contains details about a single template.

func NewTemplate 

func NewTemplate() Template

NewTemplate returns a new Template struct with initialized values. This template will not be saved to Transloadit. To do so, please use the Client.CreateTemplate function.

func (*Template) AddStep 

func (template *Template) AddStep(name string, step map[string]interface{})

AddStep will add the provided step to the Template.Content.Steps map.

func (Template) MarshalJSON added in v1.2.0 

func (template Template) MarshalJSON() ([]byte, error)

func (*Template) UnmarshalJSON added in v1.2.0 

func (template *Template) UnmarshalJSON(b []byte) error

type TemplateContent added in v1.0.0 

type TemplateContent struct {
	Steps                map[string]interface{}
	AdditionalProperties map[string]interface{}
}

TemplateContent contains details about the content of a single template. The Steps fields maps to the `steps` key in the JSON format. The AdditionalProperties field allows you to store additional keys (such as `notify_url`) on the same level as the `steps` key. For example, the following instance 

TemplateContent{
	Steps: map[string]interface{}{
		":original": map[string]interface{}{
			"robot": "/upload/handle",
		},
		"resize": map[string]interface{}{
			"robot": "/image/resize",
		},
	},
	AdditionalProperties: map[string]interface{}{
		"notify_url":           "https://example.com",
		"allow_steps_override": false,
	},
}

is represented by following JSON: 

 {
	"steps": {
		":original": {
			"robot": "/upload/handle"
		},
		"resize": {
			"robot": "/image/resize"
		}
	},
	"allow_steps_override": false,
	"notify_url": "https://example.com"
}

func (TemplateContent) MarshalJSON added in v1.3.0 

func (content TemplateContent) MarshalJSON() ([]byte, error)

func (*TemplateContent) UnmarshalJSON added in v1.3.0 

func (content *TemplateContent) UnmarshalJSON(b []byte) error

type TemplateCredential added in v1.5.0 

type TemplateCredential struct {
	ID       string                 `json:"id"`
	Name     string                 `json:"name"`
	Type     string                 `json:"type"`
	Content  map[string]interface{} `json:"content"`
	Created  string                 `json:"created,omitempty"`
	Modified string                 `json:"modified,omitempty"`
}

TemplateCredential contains details about a single template credential.

func NewTemplateCredential added in v1.5.0 

func NewTemplateCredential() TemplateCredential

NewTemplateCredential returns a new TemplateCredential struct with initialized values. This template credential will not be saved to Transloadit. To do so, please use the Client.CreateTemplateCredential function.

type TemplateCredentialList added in v1.5.0 

type TemplateCredentialList struct {
	TemplateCredential []TemplateCredential `json:"credentials"`
	OK                 string               `json:"ok"`
	Message            string               `json:"message"`
}

TemplateCredentialList contains a list of template credentials.

type TemplateList 

type TemplateList struct {
	Templates []Template `json:"items"`
	Count     int        `json:"count"`
}

TemplateList contains a list of templates.

Source Files

View all Source files

Directories

Path Synopsis

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.