API SDKs
Go SDK
Generate report with Go
Golang SDK to generate reports through the Carbone Cloud API in few lines of codes.
The source code is available on Github: https://github.com/carboneio/carbone-sdk-go
Install
go get github.com/carboneio/carbone-sdk-go
Quickstart
Try the following code to generate a report in few seconds. Insert an API key, provide the template, and the data as a stringified JSON, that's it.
package main
import (
"io/ioutil"
"log"
"github.com/carboneio/carbone-sdk-go/carbone"
)
func main() {
csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
if err != nil {
log.Fatal(err)
}
// Path to your template
templateID := "./folder/template.odt"
// Add your data here
jsonData := `{"data":{},"convertTo":"pdf"}`
reportBuffer, err := csdk.Render(templateID, jsonData)
if err != nil {
log.Fatal(err)
}
err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
if err != nil {
log.Fatal(err)
}
}
Constructor
func NewCarboneSDK(SecretAccessToken ...string) (*CSDK, error)
Function to create a new instance of CSDK (CarboneSDK).
The access token can be pass as an argument to NewCarboneSDK (args[0]
) or by the environment variable "CARBONE_TOKEN".
To set a new environment variable, use the command:
$ export CARBONE_TOKEN=your-secret-token
Check if it is set by running:
$ printenv | grep "CARBONE_TOKEN"
Example
// Carbone access token passed as parameter
csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
// Carbone access token passed as environment variable "Carbone TOKEN"
csdk, err := carbone.NewCarboneSDK()
Generate a report
func (csdk *CSDK) Render(pathOrTemplateID string, jsonData string, payload ...string) ([]byte, error)
The render function takes pathOrTemplateID
the path of your local file OR a templateID, jsonData
a stringified JSON, and an optional payload
.
It returns the report as a []byte
. Carbone engine deleted files that have not been used for a while. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.
When a template file path is passed as an argument, the function verifies if the template has been uploaded to render the report. If not, it calls AddTemplate to upload the template to the server and generate a new template ID. Then it calls RenderReport and GetReport to generate the report. If the path does not exist, an error is returned.
When a templateID is passed as an argument, the function renders with RenderReport then call GetReport to return the report. If the templateID does not exist, an error is returned.
Example
reportBuffer, err := csdk.Render("./templates/invoice.docx", `{"data":{"nane":"eric"},"convertTo":"pdf"}`, "OptionalPayload1234")
if err != nil {
log.Fatal(err)
}
// create the file
err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
if err != nil {
log.Fatal(err)
}
Upload a template
func (csdk *CSDK) AddTemplate(templateFileName string, payload ...string) (APIResponse, error)
Add the template to the API and returns an APIResponse
struct (that contains a TemplateID
).
You can add multiple times the same template and get different templateId thanks to the optional payload
.
Example
resp, err := csdk.AddTemplate("./tests/template.test.odt")
if err != nil {
t.Error(err)
}
if resp.Success == false {
t.Error(resp.Error)
}
if len(resp.Data.TemplateID) <= 0 {
t.Error(errors.New("templateId not returned from the api"))
}
fmt.Println("templateID:", resp.Data.TemplateID)
Download a template
func (csdk *CSDK) GetTemplate(templateID string) ([]byte, error)
Pass a templateID
to the function and it returns the template as []byte
. The templateID must exist otherwise an error is returned by the server.
templateData, err := csdk.GetTemplate("TemplateId")
if err != nil || len(templateData) <= 0 {
t.Error(err)
}
err = ioutil.WriteFile(filename, templateData, 0644)
if err != nil {
t.Error(err)
}
Delete a template
func (csdk *CSDK) DeleteTemplate(templateID string) (APIResponse, error)
Example
resp, err := csdk.DeleteTemplate(templateID)
if err != nil {
t.Error(err)
}
if resp.Success == false {
t.Error(resp.Error)
}
Generate a template ID
func (csdk *CSDK) GenerateTemplateID(filepath string, payload ...string) (string, error)
The Template ID is predictable and idempotent, pass the template path and it will return the templateID
.
You can get a different templateId thanks to the optional payload
.
API Token
func (csdk *CSDK) SetAccessToken(newToken string)
It sets the Carbone access token.
Carbone API version
Get
func (csdk *CSDK) SetAPIVersion(version int)
It sets the the Carbone version requested. By default, it is calling the version 2
of Carbone.
Note: You can only set a major version of carbone.
Set
func (csdk *CSDK) GetAPIVersion() (int, error)
It returns the Carbone version.