# Upgrade
In this article:
# Upgrade JavaScript SDK 2.x to 3.x
How to upgrade from SDK version 2.x to 3.x.
# Renamed interfaces
Some TypeScript interfaces have been renamed to have consistency between different resource types. Among the most used ones are:
- GetTimeSeriesMetadataDTO -> Timeseries
- PostTimeSeriesMetadataDTO -> ExternalTimeseries
- DatapointsGetAggregateDatapoint -> DatapointAggregates
- FilesMetadata -> FileInfo
You can find a comprehensive list in the changelog (opens new window).
# Events aggregate endpoints moved to a sub-API
client.events.aggregate(...)
->client.events.aggregate.count()
client.events.uniqueValuesAggregate(...)
->client.events.aggregate.uniqueValues(...)
# Timestamp-to-Date auto-conversion
The JavaScript SDK automatically converts response timestamp values to date objects. This caused a bug (opens new window) in the Raw API. The fix can introduce a breaking change if you use the Raw API, and possibly in other places.
# Helper classes removed
AssetClass, TimeSeriesClass, TimeSeriesList and AssetList contained some helper methods that have been removed.
Most of these helpers can be easily re-implemented using other SDK calls.
Some examples:
Asset.delete()
public async delete(options: DeleteOptions = {}) {
return this.client.assets.delete(
[{ id: this.id }],
options
);
}
2
3
4
5
6
Asset.subtree()
public async subtree() {
const { items } = await client.assets.list({
filter: {
assetSubtreeIds: [{ id: this.id }],
}
});
}
2
3
4
5
6
7
TimeSeriesList.getAllDatapoints(...)
public getAllDatapoints = async (options: DatapointsMultiQueryBase = {}) => {
const tsIds = this.map(({ id }) => ({ id }));
return this.client.datapoints.retrieve({
items: tsIds,
...options,
});
};
2
3
4
5
6
7
# Removed client.assets.retrieveSubtree(...)
Copies the functionality of Asset.subtree()
(read above).
# Change filter passing to client.timeseries.list
The function previously took a TimeseriesFilter
as input, and now takes a TimeseriesFilterQuery
which
corresponds closely to the API spec. All filter related fields should now be in the filter
object.
# Example:
// Old way
const timeseries = await client.timeseries.list({
assetIds: [1, 2],
unit: 'liter',
limit: 100,
});
//New way
const timeseries = await client.timeseries.list({
filter: { assetIds: [1, 2], unit: 'liter' },
limit: 100,
});
2
3
4
5
6
7
8
9
10
11
12
# Upgrade JavaScript SDK 1.x to 2.x
How to upgrade from SDK version 1.x to 2.x.
# Constructor
In 2.x.x you need to create a new SDK instance before you can use the SDK:
const client = new CogniteClient({ appId: 'YOUR APPLICATION NAME' });
Next, you need to authenticate your client by calling one of these methods on the client:
With API key:
client.loginWithApiKey({ project, apiKey });
With OAuth:
client.loginWithOAuth({
project: 'publicdata',
});
2
3
For more info about OAuth-authentication, see here.
# Changes
1.x.x | 2.x.x |
---|---|
AUTHENTICATION | |
sdk.Login.authorize(...) | See constructor-section |
sdk.Login.loginWithApiKey(...) | See constructor-section |
sdk.Logout.logout() | Removed |
sdk.Logout.retrieveLogoutUrl(...) | Removed |
ASSETS | |
sdk.Assets.create([...]) | client.assets.create([...]) |
sdk.Assets.retrieve(123) | client.assets.retrieve([{id: 123}]) |
sdk.Assets.retrieveMultiple([123, 456]) | client.assets.retrieve([{id: 123}, {id: 456}]) |
sdk.Assets.update(id, changes) | client.assets.update([{id, update: changes}]) |
sdk.Assets.updateMultiple([{id, ...changes}]) | client.assets.update([{id, update: changes}]) |
sdk.Assets.overwriteMultiple(...) | Removed |
sdk.Assets.delete([id]) | client.assets.delete([{id: 123}]) |
sdk.Assets.list({name: 'abc'}) | client.assets.list({filter: {name: 'abc'}}).autoPagingToArray({limit: 1000}) |
sdk.Assets.listDescendants(id, params) | Not implemented yet. Follow issue here (opens new window) |
sdk.Assets.search({name: 'abc'}) | client.assets.search({search: {name: 'abc'}) |
TIME SERIES | |
sdk.TimeSeries.create([...]) | client.timeseries.create([...]) |
sdk.TimeSeries.retrieve(123) | client.timeseries.retrieve([{id: 123}]) |
sdk.TimeSeries.retrieveMultiple([123, 456]) | client.timeseries.retrieve([{id: 123}, {id: 456}]) |
sdk.TimeSeries.update(id, changes) | client.timeseries.update([{id, update: changes}]) |
sdk.TimeSeries.updateMultiple([{id, ...changes}]) | client.timeseries.update([{id, update: changes}]) |
sdk.TimeSeries.list({limit: 20}) | client.timeseries.list().autoPagingToArray({limit: 20}) |
sdk.TimeSeries.search({name: 'abc'}) | client.timeseries.search({search: {name: 'abc'}}) |
DATA POINTS | |
sdk.Datapoints.insert(id, datapoints) | client.datapoints.insert([{id, datapoints}]) |
sdk.Datapoints.insertByName(...) | Removed |
sdk.Datapoints.insertMultiple([{name, datapoints}]) | Not supported using name. Use IDs instead: client.datapoints.insert([{id, datapoints}]) |
sdk.Datapoints.retrieve(id, params) | client.datapoints.retrieve({items: [{id}], ...params}) |
sdk.Datapoints.retrieveByName(...) | Removed (use ID instead) |
sdk.Datapoints.retrieveMultiple(...) | Not directly supported. Use client.datapoints.retrieve |
sdk.Datapoints.retrieveLatest(name, before) | Use IDs: client.datapoints.retrieveLatest([{id, before}]) |
client.datapoints.retrieveCSV(...) | Removed |
sdk.Datapoints.delete(name, timestamp) | Use IDs: client.datapoints.delete([{id, inclusiveBegin: timestamp, exclusiveEnd: timestamp}]) |
sdk.Datapoints.deleteRange(name, inclusiveBegin, exclusiveEnd) | Use IDs: client.datapoints.delete([{id, inclusiveBegin, exclusiveEnd}]) |
EVENTS | |
sdk.Events.create([...]) | client.events.create([...]) |
sdk.Events.retrieve(id) | client.events.retrieve([{id}]) |
sdk.Events.retrieveMultiple([123, 456]) | client.events.retrieve([{id: 123}, {id: 456}]) |
sdk.Events.update([{id, ...changes}]) | client.events.update([{id, update: changes}]) |
sdk.Events.delete([id]) | client.events.delete([{id}]) |
sdk.Events.list({limit: 20}) | client.events.list().autoPagingToArray({limit: 20}) |
sdk.Events.search({name: 'abc'}) | client.events.search({search: {name: 'abc'}}) |
FILES | |
sdk.Files.upload(fileMetadata, params) | client.files.upload(fileMetadata, fileContent?, overwrite?, waitUntilAcknowledged?) |
sdk.Files.download(id) | client.files.getDownloadUrls([{id}]) |
sdk.Files.retrieveMetadata(id) | client.files.retrieve([{id}]) |
sdk.Files.retrieveMultipleMetadata([123, 456]) | client.files.retrieve([{id: 123}, {id: 456}]) |
sdk.Files.updateMetadata(id, changes) | client.files.update([{id, update: changes}]) |
sdk.Files.updateMultipleMetadata([id, ...changes]) | client.files.update([{id, update: changes}]) |
sdk.Files.delete([id]) | client.files.delete([{id}]) |
sdk.Files.list({limit: 20}) | client.files.list().autoPagingToArray({limit: 20}) |
sdk.Files.search({name: 'abc'}) | client.files.search({search: {name: 'abc'}}) |
sdk.Files.replaceMetadata(...) | Removed |
3D | |
sdk.ThreeD.createAssetMappings(modelId, revisionId, mappings) | client.assetMappings3D.create(modelId, revisionId, mappings) |
sdk.ThreeD.createModels([name]) | client.models3D.create([{name}]) |
sdk.ThreeD.createRevisions(modelId, revisions) | client.revisions3D.create(modelId, revisions) |
sdk.ThreeD.retrieveFile(fileId, responseType) | client.files3D.retrieve(fileId) |
sdk.ThreeD.retrieveModel(modelId) | client.models3D.retrieve(modelId) |
sdk.ThreeD.retrieveRevision(modelId, revisionId) | client.models3D.retrieve(modelId, revisionId) |
sdk.ThreeD.updateModels({id, name}) | client.models3D.update([{id, update: {name}]) |
sdk.ThreeD.updateRevisions(modelId, {id, ...changes}) | client.revisions3D.update(modelId, [{id, update: changes]) |
sdk.ThreeD.updateRevisionThumbnail(...) | client.revisions3D.updateThumbnail(modelId, revisionId, fileId) |
sdk.ThreeD.deleteModels([id]) | client.models3D.delete([{id}]) |
sdk.ThreeD.deleteRevisions(modelId, [id]) | client.revisions3D.delete(modelId, [{id}]) |
sdk.ThreeD.deleteAssetMappings(modelId, revisionId, mappings) | client.assetMappings3D.delete(modelId, revisionId, mappings) |
sdk.ThreeD.listAssetMappings(modelId, revisionId, params) | client.assetMappings3D.list(modelId, revisionId, params).autoPagingToArray() |
sdk.ThreeD.listModels(params) | client.models3D.list(params).autoPagingToArray() |
sdk.ThreeD.listNodes(modelId, revisionId, params) | client.revisions3D.list3DNodes(modelId, revisionId, params).autoPagingToArray() |
sdk.ThreeD.listNodeAncestors(modelId, revisionId, params) | client.revisions3D.list3DNodeAncestors(modelId, revisionId, nodeId, params).autoPagingToArray() |
sdk.ThreeD.listRevisions(modelId, params) | client.revisions3D.list(modelId, params).autoPagingToArray() |
sdk.ThreeD.listSectors(modelId, revisionId, params) | client.viewer3D.listRevealSectors3D(modelId, revisionId, params).autoPagingToArray() |