README

Build Status Go Report Card PkgGoDev

Cloudinary Go SDK

Cloudinary is a cloud service for managing your web application's entire media management pipeline. Easily upload images and videos to the cloud using Cloudinary's comprehensive APIs and administration capabilities and easily integrate with your web application, existing or new.

For Go, Cloudinary provides a module for simplifying the integration even further. This Readme provides the basic information needed to get started with the Cloudinary Go SDK. For full documentation, take a look at the SDK guide. For a high-level introduction on Cloudinary and a step-by-step walk through of how to integrate Cloudinary in your application, see our getting started guide.

Setup

Installation

To install the Cloudinary Go SDK, use the go get command:

go get github.com/cloudinary/cloudinary-go
Configuration

For requests to our secure APIs (e.g., image uploads, asset administration) you must have the APIKey and APISecret parameters set. You can find your account-specific configuration credentials in the Dashboard page of the account console.

Setting your CloudName, APIKey and APISecret parameters can be done by initializing the Cloudinary object, or by using the CLOUDINARY_URL environment variable / system property.

The entry point of the library is the Cloudinary struct.

cld, _ := cloudinary.New()

Here's an example of setting the configuration parameters programatically:

cld, _ := cloudinary.NewFromParams("n07t21i7", "123456789012345", "abcdeghijklmnopqrstuvwxyz12")

You can also set the configuration parameters by providing the CLOUDINARY_URL value:

cld, _ := cloudinary.NewFromURL("cloudinary://123456789012345:abcdeghijklmnopqrstuvwxyz12@n07t21i7")

Learn more: Go configuration

Update

To update the Cloudinary Go SDK to the latest version, use the go get command with the -u option:

go get -u github.com/cloudinary/cloudinary-go

Usage

Upload

Assuming you have your Cloudinary configuration parameters defined (CloudName, APIKey, APISecret), uploading to Cloudinary is very simple.

The following example uploads a local JPG to the cloud:

resp, err := cld.Upload.Upload(ctx, "my_picture.jpg", uploader.UploadParams{})

The uploaded image is assigned a randomly generated public ID. The image is immediately available for a download through a CDN:

log.Println(resp.SecureURL)

// https://res.cloudinary.com/demo/image/upload/abcfrmo8zul1mafopawefg.jpg

You can also specify your own public ID:

resp, err := cld.Upload.Upload(ctx, "my_picture.jpg", uploader.UploadParams{PublicID: "sample_remote"});
if err != nil {...}
log.Println(resp.SecureURL)

// https://res.cloudinary.com/demo/image/upload/sample_remote.jpg

Learn more: Go upload

Complete SDK Example
package main

import (
	"context"
	"github.com/cloudinary/cloudinary-go"
	"github.com/cloudinary/cloudinary-go/api/admin"
	"github.com/cloudinary/cloudinary-go/api/admin/search"
	"github.com/cloudinary/cloudinary-go/api/uploader"
	"log"
)

func main() {
	// Start by creating a new instance of Cloudinary using CLOUDINARY_URL environment variable.
	// Alternatively you can use cloudinary.NewFromParams() or cloudinary.NewFromURL().
	var cld, err = cloudinary.New()
	if err != nil {
		log.Fatalf("Failed to intialize Cloudinary, %v", err)
	}

	var ctx = context.Background()

	// Upload an image to your Cloudinary account from a specified URL.
	//
	// Alternatively you can provide a path to a local file on your filesystem,
	// base64 encoded string, io.Reader and more.
	//
	// For additional information see:
	// https://cloudinary.com/documentation/upload_images
	//
	// Upload can be greatly customized by specifying uploader.UploadParams,
	// in this case we set the Public ID of the uploaded asset to "logo".
	uploadResult, err := cld.Upload.Upload(
		ctx,
		"https://cloudinary-res.cloudinary.com/image/upload/cloudinary_logo.png",
		uploader.UploadParams{PublicID: "logo"})
	if err != nil {
		log.Fatalf("Failed to upload file, %v\n", err)
	}

	log.Println(uploadResult.SecureURL)
	// Prints something like:
	// https://res.cloudinary.com/<your cloud name>/image/upload/v1615875158/logo.png

	// uploadResult contains useful information about the asset, like Width, Height, Format, etc.
	// See uploader.UploadResult struct for more details.

	// Now we can use Admin API to see the details about the asset.
	// The request can be customised by providing AssetParams.
	asset, err := cld.Admin.Asset(ctx, admin.AssetParams{PublicID: "logo"})
	if err != nil {
		log.Fatalf("Failed to get asset details, %v\n", err)
	}

	// Print some basic information about the asset.
	log.Printf("Public ID: %v, URL: %v\n", asset.PublicID, asset.SecureURL)

	// Cloudinary also provides a very flexible Search API for filtering and retrieving
	// information on all the assets in your account with the help of query expressions
	// in a Lucene-like query language.
	searchQuery := search.Query{
		Expression: "resource_type:image AND uploaded_at>1d AND bytes<1m",
		SortBy:     []search.SortByField{{"created_at": search.Descending}},
		MaxResults: 30,
	}

	searchResult, err := cld.Admin.Search(ctx, searchQuery)

	if err != nil {
		log.Fatalf("Failed to search for assets, %v\n", err)
	}

	log.Printf("Assets found: %v\n", searchResult.TotalCount)

	for _, asset := range searchResult.Assets {
		log.Printf("Public ID: %v, URL: %v\n", asset.PublicID, asset.SecureURL)
	}
}

Contributing

Please feel free to submit issues, fork the repository and send pull requests!

For more information on how to contribute, take a look at the contributing page.

Additional resources

Additional resources are available at:

Community and Support

Impact the product, hear updates, test drive new features and more! Join here.

You can open an issue through GitHub.

Stay tuned for updates, tips and tutorials: Blog , Twitter, Facebook.

License

Released under the MIT license.

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cloudinary

type Cloudinary struct {
	Config config.Configuration
	Admin  admin.API
	Upload uploader.API
}

    Cloudinary main struct

    func New

    func New() (*Cloudinary, error)

      New returns a new Cloudinary instance from environment variable.

      func NewFromConfiguration

      func NewFromConfiguration(configuration config.Configuration) (*Cloudinary, error)

        NewFromConfiguration returns a new Cloudinary instance from the provided configuration.

        func NewFromParams

        func NewFromParams(cloud string, key string, secret string) (*Cloudinary, error)

          NewFromParams returns a new Cloudinary instance from the provided parameters.

          func NewFromURL

          func NewFromURL(cloudinaryURL string) (*Cloudinary, error)

            NewFromURL returns a new Cloudinary instance from a cloudinary url.

            Source Files

            Directories

            Path Synopsis
            api
            Package api contains packages used for accessing Cloudinary API functionality.
            Package api contains packages used for accessing Cloudinary API functionality.
            admin
            Package admin is used for accessing Cloudinary Admin API functionality.
            Package admin is used for accessing Cloudinary Admin API functionality.
            admin/metadata
            Package metadata defines the structured metadata.
            Package metadata defines the structured metadata.
            uploader
            Package uploader is used for accessing Cloudinary Upload API functionality.
            Package uploader is used for accessing Cloudinary Upload API functionality.
            Package config defines the Cloudinary configuration.
            Package config defines the Cloudinary configuration.
            Package transformation defines Cloudinary Transformation.
            Package transformation defines Cloudinary Transformation.
            internal