IBM Cloud Docs
Using the Go SDK

Using the Go SDK

The IBM Analytics Engine Go SDK allows you to interact programmatically with the IBM Analytics Engine service API for serverless instances.

You can get the source code for the SDK from GitHub. See ibm-iae-go-sdk. The iaesdk library provides complete access to the IBM Analytics Engine API.

Getting the SDK

You need to download and install the SDK to use it in your Go applications. You can do this by entering the following command:

go get -u github.com/IBM/ibm-iae-go-sdk

If your application uses Go modules, you can add a suitable import to your Go application, and run:

go mod tidy

Importing packages

After you have installed the SDK, you need to import the SDK packages that you want to use in your Go applications.

For example:

import (
  "github.com/IBM/go-sdk-core/v3/core"
  "github.com/IBM/ibm-iae-go-sdk/ibmanalyticsengineapiv3"
)

Creating a client and sourcing credentials

When you connect to IBM Analytics Engine, a client is created and configured using the credential information (API key and service instance ID) that you provide. If you don't provide this information manually, these credentials can be sourced from a credentials file or from environment variables.

You can retrieve the service instance ID when you create service credentials or through the CLI. See Retrieving service endpoints.

To use the IBM Analytics Engine Go SDK, you need the following values:

  • IAM_API_KEY: The API key generated when creating the service credentials. You can retrieve by viewing the service credentials on the IBM Cloud dashboard.
  • instance_guid: The value in resource_instance_id generated when the service credentials are created. You can retrieve by viewing the service credentials on the IBM Cloud dashboard.
  • IAE_ENDPOINT_URL : The service endpoint URL including the https:// protocol. See Service endpoints.

Initializing the configuration

The Go SDK allows you to construct the service client in one of two ways by:

  • By setting client options programmatically

    You can construct an instance of the IBM Analytics Engine service client by specifying various client options, like the authenticator and service endpoint URL, programmatically:

    package main
    
    import (
     "fmt"    
    "github.com/IBM/go-sdk-core/v3/core"
    "github.com/IBM/ibm-iae-go-sdk/ibmanalyticsengineapiv3"
    )
    
    func main() {
        // Create an IAM authenticator.
        authenticator := &core.IamAuthenticator{
            ApiKey: "{apikey}", // eg "0viPHOY7LbLNa9eLftrtHPpTjoGv6hbLD1QalRXikliJ"
            URL: "{api auth url}", // "https://iam.cloud.ibm.com/identity/token"
        }
    
        // Construct an "options" struct for creating the service client.
        options := &ibmanalyticsengineapiv3.IbmAnalyticsEngineApiV3Options{
            Authenticator: authenticator,
            URL: "{url}",  // eg "https://api.us-south.ae.cloud.ibm.com"
        }
    
        // Construct the service client.
        ibmAnalyticsEngineApiService, err := ibmanalyticsengineapiv3.NewIbmAnalyticsEngineApiV3(options)
        if err != nil {
            panic(err)
        }
    
        // Service operations can now be invoked using the "ibmAnalyticsEngineApiService" variable.
    }
    
  • By using external configuration properties

    To avoid hard-coding sourcing credentials, you can store these values in configuration properties outside of your application.

    To use configuration properties:

    1. Define the configuration properties to be used by your application. These properties can be implemented as:

      • Exported environment variables
      • Values stored in a credentials file

      The following example shows using environment variables. Each environment variable must be prefixed by IBM_ANALYTICS_ENGINE_API.

      export IBM_ANALYTICS_ENGINE_API_URL=<IAE_ENDPOINT_URL>
      export IBM_ANALYTICS_ENGINE_API_AUTH_TYPE=iam
      export IBM_ANALYTICS_ENGINE_API_APIKEY=<IAM_API_KEY>
      

      IBM_ANALYTICS_ENGINE_API is the default service name for the IBM Analytics Engine API client which means that the SDK will by default look for properties that start with this prefix folded to uppercase.

    2. Build the service client:

      // Create an IAM authenticator.
      authenticator := &core.IamAuthenticator{
         ApiKey: "{apikey}", // eg "0viPHOY7LbLNa9eLftrtHPpTjoGv6hbLD1QalRXikliJ"
         URL: "{api auth url}", //https://iam.cloud.ibm.com/identity/token
      }
      
      // Construct an "options" struct for creating the service client.
      options := &ibmanalyticsengineapiv3.IbmAnalyticsEngineApiV3Options{
         Authenticator: authenticator,
         URL: "{url}",  // eg "https://api.us-south.ae.cloud.ibm.com"
      }
      
      // Construct the service client.
      service, err := ibmanalyticsengineapiv3.NewIbmAnalyticsEngineApiV3(options)
      if err != nil {
         panic(err)
      }
      

Code samples using iaesdk

In addition to the sample code snippets in this section, you can work with Go code samples from the IBM Analytics Engine V3 API reference.

The following code samples show you how to:

  • Retrieve the details of a single instance:

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) GetInstance(getInstanceOptions *GetInstanceOptions) (result *Instance, response *core.DetailedResponse, err error)
    

    Example request:

    func main() {
        // Construct an instance of the GetInstanceOptions model
        getInstanceOptionsModel := new(ibmanalyticsengineapiv3.GetInstanceOptions)
        getInstanceOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
    
        _, response, _ := ibmAnalyticsEngineApiService.GetInstance(getInstanceOptionsModel)
        fmt.Println(response)
    }
    
  • Deploy a Spark application on a given serverless Spark instance:

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) CreateApplication(createApplicationOptions *CreateApplicationOptions) (result *ApplicationResponse, response *core.DetailedResponse, err error)
    

    Sample request:

    func main() {
        // Construct an instance of the CreateApplicationOptions model
        createApplicationOptionsModel := new(ibmanalyticsengineapiv3.CreateApplicationOptions)
        createApplicationOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
        createApplicationOptionsModel.Application = core.StringPtr("cos://bucket_name.my_cos/my_spark_app.py")
        createApplicationOptionsModel.Class = core.StringPtr("IbmAnalyticsEngineApi")
        createApplicationOptionsModel.Arguments = []string{"/opt/ibm/spark/examples/src/main/resources/people.txt"}
        createApplicationOptionsModel.Conf = make(map[string]interface{})
        createApplicationOptionsModel.Env = make(map[string]interface{})
    
        _, applicationCreationResponse, _ := ibmAnalyticsEngineApiService.CreateApplication(createApplicationOptionsModel)
        fmt.Println(applicationCreationResponse)
    }
    
  • Retrieve all Spark applications:

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) ListApplications(listApplicationsOptions *ListApplicationsOptions) (result *ApplicationCollection, response *core.DetailedResponse, err error)
    

    Example request:

    func main() {
        // Construct an instance of the ListApplicationsOptions model
        listApplicationsOptionsModel := new(ibmanalyticsengineapiv3.ListApplicationsOptions)
        listApplicationsOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
    
        _, applicationCollection, _ := ibmAnalyticsEngineApiService.ListApplications(listApplicationsOptionsModel)
        fmt.Println(applicationCollection)
    }
    
  • Retrieve the details of a given Spark application:

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) GetApplication(getApplicationOptions *GetApplicationOptions) (result *ApplicationGetResponse, response *core.DetailedResponse, err error)
    

    Example request:

    func main() {
        // Construct an instance of the GetApplicationOptions model
        getApplicationOptionsModel := new(ibmanalyticsengineapiv3.GetApplicationOptions)
        getApplicationOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
        getApplicationOptionsModel.ApplicationID = core.StringPtr("db933645-0b68-4dcb-80d8-7b71a6c8e542")
    
        _, applicationGetResponse, _ := ibmAnalyticsEngineApiService.GetApplication(getApplicationOptionsModel)
        fmt.Println(applicationGetResponse)
    }
    
  • Stop a running application identified by the app_id identifier. This is an idempotent operation. Performs no action if the requested application is already stopped or completed.

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) DeleteApplication(deleteApplicationOptions *DeleteApplicationOptions) (response *core.DetailedResponse, err error)
    

    Example request:

    func main() {
        // Construct an instance of the DeleteApplicationOptions model
        deleteApplicationOptionsModel := new(ibmanalyticsengineapiv3.DeleteApplicationOptions)
        deleteApplicationOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
        deleteApplicationOptionsModel.ApplicationID = core.StringPtr("db933645-0b68-4dcb-80d8-7b71a6c8e542")
    
        applicationDeletionResponse, _ := ibmAnalyticsEngineApiService.DeleteApplication(deleteApplicationOptionsModel)
        fmt.Println(applicationDeletionResponse)
    }
    
  • Return the state of a given application:

    (ibmAnalyticsEngineApi *IbmAnalyticsEngineApiV3) GetApplicationState(getApplicationStateOptions *GetApplicationStateOptions) (result *ApplicationGetStateResponse, response *core.DetailedResponse, err error)
    

    Example request:

    func main() {
        // Construct an instance of the GetApplicationStateOptions model
        getApplicationStateOptionsModel := new(ibmanalyticsengineapiv3.GetApplicationStateOptions)
        getApplicationStateOptionsModel.InstanceID = core.StringPtr("dc0e9889-eab2-4t9e-9441-566209499546")
        getApplicationStateOptionsModel.ApplicationID = core.StringPtr("db933645-0b68-4dcb-80d8-7b71a6c8e542")
    
        _, applicationGetStateResponse, _ := ibmAnalyticsEngineApiService.GetApplicationState(getApplicationStateOptionsModel)
        fmt.Println(applicationGetStateResponse)
    }