Connector operations

Updated at:

Use the DataHub Java SDK to create, delete, query, update, and manage connectors.

Create a connector

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector to create.

columnFields

List

The fields to synchronize.

sinkStartTime

long

The start time for sinking data from DataHub. Unit: ms.

config

SinkConfig

The configuration of the specified connector type.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code examples

ODPS example

public static void createConnector(String projectName,String topicName) {
    List<String> columnFields = Arrays.asList("field1", "field2");
  	@Value("${datahub.accessId}")
		String accessId;
		@Value("${datahub.accessKey}")
  	String accessKey;
    SinkOdpsConfig config = new SinkOdpsConfig() {{
        setEndpoint(Constant.odps_endpoint);
        setProject(Constant.odps_project);
        setTable(Constant.odps_table);
        setAccessId(Constant.odps_accessId);
        setAccessKey(Constant.odps_accessKey);
        setPartitionMode(PartitionMode.SYSTEM_TIME);
        setTimeRange(60);
    }};
    //Set partition format
    SinkOdpsConfig.PartitionConfig partitionConfig = new SinkOdpsConfig.PartitionConfig() {{
        addConfig("ds", "%Y%m%d");
        addConfig("hh", "%H");
        addConfig("mm", "%M");
    }};
    config.setPartitionConfig(partitionConfig);
    try {
        //Create Connector
        datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_ODPS, columnFields, config);
        System.out.println("create  connector successful");
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());        
    }
}

OSS example

    public static void createOssConnector(String projectName,String topicName) {
        List<String> columnFields = Arrays.asList("field1", "field2");
        @Value("${datahub.accessId}")
				String accessId;
				@Value("${datahub.accessKey}")
  			String accessKey;
        SinkOssConfig config = new SinkOssConfig() {{
            setAccessId(Constant.oss_accessId);
            setAccessKey(Constant.oss_accessKey);
            setAuthMode(AuthMode.STS);
            setBucket(Constant.oss_bucket);
            setEndpoint(Constant.oss_endpoint);
            setPrefix(Constant.oss_prefix);
            setTimeFormat(Constant.oss_timeFormat);
            setTimeRange(60);

        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName,topicName, ConnectorType.SINK_OSS, columnFields, config);
            System.out.println("create  connector successful");
        } catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());
        }
    }

TableStore example

       public static void createOtsConnector(String projectName,String topicName) {
        List<String> columnFields = Arrays.asList("field1", "field2");
  			@Value("${datahub.accessId}")
				String accessId;
				@Value("${datahub.accessKey}")
  			String accessKey;         
        final SinkOtsConfig config = new SinkOtsConfig() {{
            setAccessId(Constant.ots_accessId);
            setAccessKey(Constant.ots_accessKey);
            setEndpoint(Constant.ots_endpoint);
            setInstance(Constant.ots_instance);
            setTable(Constant.ots_table);
            setAuthMode(AuthMode.AK);
        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_OTS, columnFields, config);
            System.out.println("create  connector successful");
        }  catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());    
        }
    }

Hologres example

       public static void createHoloConnector(String projectName,String topicName) {
       @Value("${datahub.accessId}")
			 String accessId;
	     @Value("${datahub.accessKey}")
  	   String accessKey;
        List<String> columnFields = Arrays.asList("field1", "field2");
        final SinkHologresConfig config = new SinkHologresConfig() {{
            setAccessId(Constant.accessId);
            setAccessKey(Constant.accessKey);
            setProjectName(Constant.projectName);
            setTopicName(Constant.topicName);
            setAuthMode(AuthMode.AK);
            setInstanceId(Constant.instanceId);
            //Set time format
            setTimestampUnit(TimestampUnit.MILLISECOND);
        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_HOLOGRES, columnFields, config);
            System.out.println("create  connector successful");
        }  catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());    
        }
    }

ElasticSearch example

    public static void createEsConnector(String projectName,String topicName){
   	@Value("${datahub.accessId}")
		String accessId;
		@Value("${datahub.accessKey}")
		String accessKey;
        List<String> columnFields = Arrays.asList("field1", "field2");
        final SinkEsConfig config = new SinkEsConfig() {{
            setEndpoint(Constant.es_endpoint);
            setIdFields(Constant.es_fields);
            setIndex(Constant.es_index);
            setPassword(Constant.es_password);
            setProxyMode(Constant.es_proxyMode);
            setTypeFields(Constant.es_typeFields);
            setUser(Constant.es_user);

        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_ES, columnFields, config);
            System.out.println("create  connector successful");
        } catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());
        }
    }

Function Compute example

   public static void createFcConnector(String projectName,String topicName){
    @Value("${datahub.accessId}")
		String accessId;
		@Value("${datahub.accessKey}")
		String accessKey;   
     List<String> columnFields = Arrays.asList("field1", "field2");
        final SinkFcConfig config = new SinkFcConfig() {{
            setEndpoint(Constant.fc_endpoint);
            setAccessId(Constant.fc_accessId);
            setAccessKey(Constant.fc_accessKey);
            setAuthMode(AuthMode.AK);
            setFunction(Constant.fc_function);
            setService(Constant.fc_service);

        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_FC, columnFields, config);
            System.out.println("create  connector successful");
        } catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());

        }
    }

MySQL example

    public static void createMysqlConnector(String projectName,String topicName){
        List<String> columnFields = Arrays.asList("field1", "field2");

        final SinkMysqlConfig config = new SinkMysqlConfig() {{
         setDatabase( Constant.mysql_database);
         setHost(Constant.mysql_host);
         setInsertMode(InsertMode.OVERWRITE);
         setPassword(Constant.mysql_password);
         setPort(Constant.mysql_port);
         setTable(Constant.mysql_table);
         setUser(Constant.mysql_user);
        }};

        try {
            //Create Connector
            datahubClient.createConnector(projectName, topicName, ConnectorType.SINK_MYSQL, columnFields, config);
            System.out.println("create  connector successful");
        } catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());  
        }
    }

Delete a connector

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector to create.

columnFields

List

The fields to synchronize.

sinkStartTime

long

The start time for sinking data from DataHub. Unit: ms.

config

SinkConfig

The configuration of the specified connector type.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void deleteConnector(String projectName,String topicName) {
  try {
      datahubClient.deleteConnector(projectName, topicName, ConnectorType.SINK_ODPS);
      System.out.println("delete  connector successful");
  } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());    
  }
}

Query a connector

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector to create.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void getConnector(String projectName,String topicName) {
  try {
      GetConnectorResult getConnectorResult = datahubClient.getConnector(projectName, topicName, ConnectorType.SINK_ODPS);
      System.out.println(getConnectorResult.getState() + "\t" + getConnectorResult.getSubId());
      for (String fieldName : getConnectorResult.getColumnFields()) {
          System.out.println(fieldName);
      }
  } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());

  }
}

Update a connector

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector to create.

config

SinkConfig

The configuration of the specified connector type.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void updateConnector(String projectName,String topicName) {
  @Value("${datahub.accessId}")
	String accessId;
	@Value("${datahub.accessKey}")
	String accessKey;
    SinkOdpsConfig config = (SinkOdpsConfig) datahubClient.getConnector(projectName, topicName, ConnectorType.SINK_ODPS).getConfig();
    //Modify ak
    config.setTimeRange(100);
    config.setAccessId(accessId);
    config.setAccessKey(accessKey);
    //Modify timestamp type
    config.setTimestampUnit(ConnectorConfig.TimestampUnit.MICROSECOND);
    try {
        datahubClient.updateConnector(projectName, topicName, ConnectorType.SINK_ODPS, config);
        System.out.println("update  connector successful");
    }  catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
    }
}

More operations

Update connector field

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

connectorId

String

The ID of the connector to update.

columnFields

List

New import fields.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example
    public static void updateConnector(String projectName,String topicName) {
        String connectorId = "";
        //columnField represents all fields synchronized to downstream, not just new fields
        List<String> columnField = new ArrayList<>();
        columnField.add("f1");
        try {
            batchClient.updateConnector(projectName, topicName,connectorId,columnField);
            System.out.println("update  connector successful");
        }  catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());
        }
    }

Update connector state

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector.

connectorState

The state of the connector. Valid values: ConnectorState.STOPPED and ConnectorState.RUNNING.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example
public static void updateConnectorState(String projectName,String topicName) {
      try {
          datahubClient.updateConnectorState(projectName, topicName, ConnectorType.SINK_ODPS, ConnectorState.STOPPED);
          datahubClient.updateConnectorState(projectName, topicName, ConnectorType.SINK_ODPS, ConnectorState.RUNNING);
          System.out.println("update  connector state successful");
      } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
      }
  }

Update connector offset

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

ConnectorType

ConnectorType

The type of connector.

shardId

String

The ID of the shard. If shardId is null, the offsets for all shards are updated.

offset

ConnectorOffset

The connector offset.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example
public static void updateConnectorOffset(String projectName,String topicName) {
    ConnectorOffset offset = new ConnectorOffset() {{
        setSequence(10);
        setTimestamp(1000);
    }};
    try {
        //To update Connector position, you need to stop the Connector first
        datahubClient.updateConnectorState(projectName, topicName, ConnectorType.SINK_ODPS, ConnectorState.STOPPED);
        datahubClient.updateConnectorOffset(projectName, topicName, ConnectorType.SINK_ODPS, shardId, offset);
        datahubClient.updateConnectorState(projectName, topicName, ConnectorType.SINK_ODPS, ConnectorState.RUNNING);
        System.out.println("update  connector offset successful");
    }  catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
    }
}

List connectors

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

 public static void listConnector(String projectName,String topicName) {
  try {
       ListConnectorResult listConnectorResult = datahubClient.listConnector(projectName, topicName);
      for (String cName : listConnectorResult.getConnectorNames()) {
          System.out.println(cName);
      }
  } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
   }
 }

Query connector shard status

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

connectorType

ConnectorType

The type of connector.

shardId

String

The id of the shard.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void getConnectorShardStatusByShard(String projectName,String topicName,String shardId) {
    try {
        ConnectorShardStatusEntry connectorShardStatusEntry = datahubClient.getConnectorShardStatus(projectName, topicName, ConnectorType.SINK_ODPS, shardId);
        System.out.println(connectorShardStatusEntry.getState() + "\t"
                + connectorShardStatusEntry.getCurrSequence() + "\t"
                + connectorShardStatusEntry.getDiscardCount() + "\t"
                + connectorShardStatusEntry.getUpdateTime());
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
    }
}
public static void getConnectorShardStatus(String projectName,String topicName) {
    try {
        GetConnectorShardStatusResult getConnectorShardStatusResult = datahubClient.getConnectorShardStatus(projectName, topicName, ConnectorType.SINK_ODPS);
        for (Map.Entry<String, ConnectorShardStatusEntry> entry : getConnectorShardStatusResult.getStatusEntryMap().entrySet()) {
            System.out.println(entry.getKey() + " : " + entry.getValue().getState() + "\t"
                    + entry.getValue().getCurrSequence() + "\t"
                    + entry.getValue().getDiscardCount() + "\t"
                    + entry.getValue().getUpdateTime());
        }
    } catch (DatahubClientException e) {
            System.out.println(e.getErrorMessage());
    }
}

Restart a connector

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

connectorType

ConnectorType

The type of connector.

shardId

String

The id of the shard.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void reloadConnector(String projectName,String topicName ) {
    try {
        datahubClient.reloadConnector(projectName, topicName, ConnectorType.SINK_ODPS);
        System.out.println("reload connector successful");
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());      
    }
}
public static void reloadConnectorByShard(String projectName,String topicName,String shardId) {
    try {
        datahubClient.reloadConnector(projectName, topicName, ConnectorType.SINK_ODPS, shardId);
        System.out.println("reload connector successful");
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());

    }
}

Query connector completion time

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

connectorType

ConnectorType

The type of connector.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void getDoneTime(String projectName,String topicName ) {
    try {
        GetConnectorDoneTimeResult getConnectorDoneTimeResult = datahubClient.getConnectorDoneTime(projectName, topicName, ConnectorType.SINK_ODPS);
        System.out.println(getConnectorDoneTimeResult.getDoneTime());
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());

    }
}

Update VPC whitelist

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

vpcids

String

The VPC IDs to update.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void updateProjectVpcWhitelist(String projectName) {
    String vpcid = "12345";
    try {
        datahubClient.updateProjectVpcWhitelist(projectName, vpcid);
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());
    }
}

Add new field to connector

You can add new fields to a connector. The corresponding columns must already exist in the MaxCompute table and match those in DataHub.

Parameters

Parameter

Type

Description

projectName

String

The name of the project.

topicName

String

The name of the topic.

connectorType

ConnectorType

The type of connector.

fieldName

String

The field to append. The field value must allow null.

Exceptions

Exception class

Error code

Description

DatahubClientException

-

The base class for all exceptions.

InvalidParameterException

InvalidParameter

InvalidCursor

A parameter is set to an invalid value.

AuthorizationFailureException

Unauthorized

Failed to parse the authorization signature. Check whether the AccessKey is correct.

ResourceNotFoundException

ResourceNotFound

NoSuchProject

NoSuchTopic

NoSuchShard

NoSuchSubscription

NoSuchConnector

NoSuchMeteringInfo

The specified resource does not exist.

Note

After a split or merge operation, sending other requests immediately may trigger this exception.

Code example

public static void appendConnectorField(String projectName,String topicName) {
    String newField = "newfield";
    try {
        //Requires that both the topic schema and MaxCompute table have the column newfield, and the table structures are completely consistent
        datahubClient.appendConnectorField(projectName, topicName, ConnectorType.SINK_ODPS, newField);
    } catch (DatahubClientException e) {
        System.out.println(e.getErrorMessage());

    }
}

/