Class ModelDerivativeClient
Namespace: Autodesk.ModelDerivative
Assembly: Autodesk.ModelDerivative.dll
Represents a collection of functions to interact with the API endpoints
public class ModelDerivativeClient
Inheritance
Inherited Members
object.Equals(object) , object.Equals(object, object) , object.GetHashCode() , object.GetType() , object.MemberwiseClone() , object.ReferenceEquals(object, object) , object.ToString()
Constructors
ModelDerivativeClient(SDKManager)
public ModelDerivativeClient(SDKManager sdkManager)
Parameters
sdkManager
SDKManager
Methods
DeleteManifestAsync(string, string, Region, bool)
Operation: Delete Manifest
Deletes the manifest of the specified source design. It also deletes all derivatives (translated output files) generated from the source design. However, it does not delete the source design.
Note: This operation is idempotent. So, if you call it multiple times, even when no manifest exists, will still return a successful response (200).
public Task<DeleteManifest> DeleteManifestAsync(string accessToken, string urn, Region region = Region.US, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
FetchSpecificPropertiesAsync(string, string, string, SpecificPropertiesPayload, Region, XAdsDerivativeFormat, string, bool)
Operation: Fetch Specific Properties
Queries the objects in the Model View (Viewable) specified by the modelGuid
parameter and returns the specified properties in a paginated list. You can limit the number of objects to be queried by specifying a filter using the query
attribute in the request body.
Note: A design file must be translated to SVF or SVF2 before you can query object properties.
Before you call this operation:
- Use the List Model Views operation to obtain the list of Model Views in the source design.
- Pick the ID of the Model View you want to query and specify that ID as the value for the
modelGuid
parameter.
public Task<SpecificProperties> FetchSpecificPropertiesAsync(string accessToken, string urn, string modelGuid, SpecificPropertiesPayload specificPropertiesPayload, Region region = Region.US, XAdsDerivativeFormat xAdsDerivativeFormat = XAdsDerivativeFormat.Latest, string acceptEncoding = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
modelGuid
string
The ID of the Model View you are querying. Use the List Model Views operation to get the IDs of the Model Views in the source design.
specificPropertiesPayload
SpecificPropertiesPayload
(optional)
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
xAdsDerivativeFormat
XAdsDerivativeFormat
Specifies what Object IDs to return, if the design has legacy SVF derivatives generated by the BIM Docs service. Possible values are:
latest
- (Default) Return SVF2 Object IDs.fallback
- Return SVF Object IDs.
Note:
- This parameter applies only to designs with legacy SVF derivatives generated by the BIM 360 Docs service.
- The BIM 360 Docs service now generates SVF2 derivatives. SVF2 Object IDs may not be compatible with the SVF Object IDs previously generated by the BIM 360 Docs service. Setting this parameter to fallback may resolve backward compatibility issues resulting from Object IDs of legacy SVF derivatives being retained on the client side.
- If you use this parameter with one derivative (URN), you must use it consistently across the following:
- Create Translation Job (for OBJ output)
- Fetch Object Tree
- Fetch All Properties
- Fetch Specific Properties (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
GetAllPropertiesAsync(string, string, string, Region, string, bool, XAdsDerivativeFormat, int, string, bool)
Operation: Fetch All Properties
Returns a list of properties of all objects in the Model View specified by the modelGuid
parameter.
This operation returns properties of all objects by default. However, you can restrict the results to a specific object by specifying its ID as the objectid
parameter.
Properties are returned as a flat list, ordered, by their objectid
. The objectid
is a non-persistent ID assigned to an object when the source design is translated to the SVF or SVF2 format. This means that:
- A design file must be translated to SVF or SVF2 before you can retrieve properties.
- The
objectid
of an object can change if the design is translated to SVF or SVF2 again. If you require a persistent ID across translations, useexternalId
to reference objects, instead ofobjectid
.
Before you call this operation:
- Use the List Model Views operation to obtain the list of Model Views (Viewables) in the source design.
- Pick the ID of the Model View you want to query and specify that ID as the value for the
modelGuid
parameter.
Tip: Use Fetch Specific Properties to retrieve only the objects and properties of interest. What’s more, the response is paginated. So, when the number of properties returned is large, responses start arriving more promptly.
public Task<Properties> GetAllPropertiesAsync(string accessToken, string urn, string modelGuid, Region region = Region.US, string acceptEncoding = null, bool xAdsForce = false, XAdsDerivativeFormat xAdsDerivativeFormat = XAdsDerivativeFormat.Latest, int objectid = 0, string forceget = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
modelGuid
string
The ID of the Model View you are querying. Use the List Model Views operation to get the IDs of the Model Views in the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
xAdsForce
bool
true
: Forces the system to parse property data all over again. Use this option to retrieve an object tree when previous attempts have failed.
false
: (Default) Use previously parsed property data to extract the object tree. (optional)
xAdsDerivativeFormat
XAdsDerivativeFormat
Specifies what Object IDs to return, if the design has legacy SVF derivatives generated by the BIM Docs service. Possible values are:
latest
- (Default) Return SVF2 Object IDs.fallback
- Return SVF Object IDs.
Note:
- This parameter applies only to designs with legacy SVF derivatives generated by the BIM 360 Docs service.
- The BIM 360 Docs service now generates SVF2 derivatives. SVF2 Object IDs may not be compatible with the SVF Object IDs previously generated by the BIM 360 Docs service. Setting this parameter to fallback may resolve backward compatibility issues resulting from Object IDs of legacy SVF derivatives being retained on the client side.
- If you use this parameter with one derivative (URN), you must use it consistently across the following:
- Create Translation Job (for OBJ output)
- Fetch Object Tree
- Fetch All Properties
- Fetch Specific Properties (optional)
objectid
int
The Object ID of the object you want to restrict the response to. If you do not specify this parameter, all properties of all objects within the Model View are returned. (optional)
forceget
string
true
: Retrieves large resources, even beyond the 20 MB limit. If exceptionally large (over 800 MB), the system acts as if forceget
is false
.
false
: (Default) Does not retrieve resources if they are larger than 20 MB. (optional)
throwOnError
bool
Returns
Task <Properties >
Task of Properties
Exceptions
Thrown when an API call fails.
GetDerivativeUrlAsync(string, string, string, Region, int, string, bool)
Operation: Fetch Derivative Download URL
Returns a download URL and a set of signed cookies, which lets you securely download the derivative specified by the derivativeUrn
parameter. The signed cookies have a lifetime of 6 hours. You can use range parameters with the returned download URL to download the derivative in chunks, in parallel.
public Task<DerivativeDownload> GetDerivativeUrlAsync(string accessToken, string derivativeUrn, string urn, Region region = Region.US, int minutesExpiration = 0, string responseContentDisposition = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
derivativeUrn
string
The URL-encoded URN of the derivative. Use the Fetch Manifest operation to obtain the URNs of derivatives for the specified source design.
urn
string
The URL-safe Base64 encoded URN of the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
minutesExpiration
int
Specifies how many minutes the signed cookies should remain valid. Default value is 360 minutes. The value you specify must be lower than the default value for this parameter. If you specify a value greater than the default value, the Model Derivative service will return an error with an HTTP status code of 400
. (optional)
responseContentDisposition
string
The value that must be specified as the response-content-disposition
query string parameter with the download URL. Must begin with attachment
. This value defaults to the default value corresponding to the derivative/file. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
GetFormatsAsync(string, string, string, bool)
Operation: List Supported Formats
Returns an up-to-date list of supported translations. This operation also provides information on the types of derivatives that can be generated for each source design file type. Furthermore, it allows you to obtain a list of translations that have changed since a specified date.
See the Supported Translation Formats table for more details.
Note: We keep adding new file formats to our supported translations list, constantly.
public Task<SupportedFormats> GetFormatsAsync(string accessToken, string ifModifiedSince = null, string acceptEncoding = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
ifModifiedSince
string
Specifies a date in the Day of the week, DD Month YYYY HH:MM:SS GMT
format. The response will contain only the formats modified since the specified date and time. If you specify an invalid date, the response will contain all supported formats. If no changes have been made after the specified date, the service returns HTTP status 304
, NOT MODIFIED. (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
GetManifestAsync(string, string, Region, string, bool)
Operation: Fetch Manifest
Retrieves the manifest of the specified source design.
The manifest is a JSON file containing information about all the derivatives translated from the specified source design. It contains information such as the URNs of the derivatives, the translation status of each derivative, and much more.
The first time you translate a source design, the Model Derivative service creates a manifest for that design. Thereafter, every time you translate that source design, even to a different format, the Model Derivative service updates the same manifest. It does not create a new manifest. Instead, the manifest acts like a central registry for all the derivatives of your source design created through the Model Derivative service.
When the Model Derivative service starts a translation job (as a result of a request you make using Create Translation Job ), it keeps on updating the manifest at regular intervals. So, you can use the manifest to check the status and progress of each derivative that is being generated. When multiple derivatives have been requested each derivative may complete at a different time. So, each derivative has its own status
attribute. The manifest also contains an overall status
attribute. The overall status
becomes complete
when the status
of all individual derivatives become complete.
Once the translation status of a derivative is complete
you can download the derivative.
Note: You cannot download 3D SVF2 derivatives.
public Task<Manifest> GetManifestAsync(string accessToken, string urn, Region region = Region.US, string acceptEncoding = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
GetModelViewsAsync(string, string, Region, string, bool)
Operation: List Model Views
Returns a list of Model Views (Viewables) in the source design specified by the urn
parameter. It also returns an ID that uniquely identifies the Model View. You can use these IDs with other metadata operations to obtain information about the objects within those Model Views.
Designs created with applications like Fusion 360 and Inventor contain only one Model View per design. Applications like Revit allow multiple Model Views per design.
Note: You can retrieve metadata only from a design that has already been translated to SVF or SVF2.
public Task<ModelViews> GetModelViewsAsync(string accessToken, string urn, Region region = Region.US, string acceptEncoding = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
throwOnError
bool
Returns
Task <ModelViews >
Exceptions
Thrown when an API call fails.
GetObjectTreeAsync(string, string, string, Region, string, bool, XAdsDerivativeFormat, string, int, string, bool)
Operation: Fetch Object tree
Retrieves the structured hierarchy of objects, known as an object tree, from the specified Model View (Viewable) within the specified source design. The object tree represents the arrangement and relationships of various objects present in that Model View.
Note: A design file must be translated to SVF or SVF2 before you can retrieve its object tree.
Before you call this operation:
- Use the List Model Views operation to obtain the list of Model Views in the source design.
- Pick the ID of the Model View you want to query and specify that ID as the value for the
modelGuid
parameter.
public Task<ObjectTree> GetObjectTreeAsync(string accessToken, string urn, string modelGuid, Region region = Region.US, string acceptEncoding = null, bool xAdsForce = false, XAdsDerivativeFormat xAdsDerivativeFormat = XAdsDerivativeFormat.Latest, string forceget = null, int objectid = 0, string level = null, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
modelGuid
string
The ID of the Model View you are extracting the object tree from. Use the List Model Views operation to get the IDs of the Model Views in the source design.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
acceptEncoding
string
A comma separated list of the algorithms you want the response to be encoded in, specified in the order of preference.
If you specify gzip
or *
, content is compressed and returned in gzip format. (optional)
xAdsForce
bool
true
: Forces the system to parse property data all over again. Use this option to retrieve an object tree when previous attempts have failed.
false
: (Default) Use previously parsed property data to extract the object tree. (optional)
xAdsDerivativeFormat
XAdsDerivativeFormat
Specifies what Object IDs to return, if the design has legacy SVF derivatives generated by the BIM Docs service. Possible values are:
latest
- (Default) Return SVF2 Object IDs.fallback
- Return SVF Object IDs.
Note:
- This parameter applies only to designs with legacy SVF derivatives generated by the BIM 360 Docs service.
- The BIM 360 Docs service now generates SVF2 derivatives. SVF2 Object IDs may not be compatible with the SVF Object IDs previously generated by the BIM 360 Docs service. Setting this parameter to fallback may resolve backward compatibility issues resulting from Object IDs of legacy SVF derivatives being retained on the client side.
- If you use this parameter with one derivative (URN), you must use it consistently across the following:
- Create Translation Job (for OBJ output)
- Fetch Object Tree
- Fetch All Properties
- Fetch Specific Properties (optional)
forceget
string
true
: Retrieves large resources, even beyond the 20 MB limit. If exceptionally large (over 800 MB), the system acts as if forceget
is false
.
false
: (Default) Does not retrieve resources if they are larger than 20 MB. (optional)
objectid
int
If specified, retrieves the sub-tree that has the specified Object ID as its parent node. If this parameter is not specified, retrieves the entire object tree. (optional)
level
string
Specifies how many child levels of the hierarchy to return, when the objectid
parameter is specified. Currently supports only level
= 1
. (optional)
throwOnError
bool
Returns
Task <ObjectTree >
Exceptions
Thrown when an API call fails.
GetThumbnailAsync(string, string, Width, Height, Region, bool)
Operation: Fetch Thumbnail
Downloads a thumbnail of the specified source design.
public Task<Stream> GetThumbnailAsync(string accessToken, string urn, Width width = Width.NUMBER_200, Height height = Height.NUMBER_200, Region region = Region.US, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
width
Width
Width of thumbnail in pixels.
Possible values are: 100
, 200
, 400
If width
is omitted, but height
is specified, width
defaults to height
. If both width
and height
are omitted, the server will return a thumbnail closest to 200
, if such a thumbnail is available. (optional)
height
Height
Height of thumbnails.
Possible values are: 100
, 200
, 400
.
If height
is omitted, but width
is specified, height
defaults to width
. If both width
and height
are omitted, the server will return a thumbnail closest to 200
, if such a thumbnail is available. (optional)
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
HeadCheckDerivativeAsync(string, string, string, Region, bool)
Operation: Check Derivative Details
Returns information about the specified derivative.
Use this operation to determine the total content length of a derivative before you download it. If the derivative is large, you can choose to download the derivative in chunks, by specifying a chunk size using the Range
parameter parameter.
public Task<HttpResponseMessage> HeadCheckDerivativeAsync(string accessToken, string urn, string derivativeUrn, Region region = Region.US, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The URL-safe Base64 encoded URN of the source design.
derivativeUrn
string
The URL-encoded URN of the derivative. Check the manifest of the source design to get the URNs of the derivatives available for download.
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
throwOnError
bool
Returns
Exceptions
Thrown when an API call fails.
SpecifyReferencesAsync(string, string, SpecifyReferencesPayload, Region, bool)
Operation: Specify References
Specifies the location of the files referenced by the specified source design.
When you call Create Translation Job , set checkReferences
to true
. The Model Derivative service will then use the details you specify in this operation to locate and download the referenced files.
public Task<SpecifyReferences> SpecifyReferencesAsync(string accessToken, string urn, SpecifyReferencesPayload referencesPayload, Region region = Region.US, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
urn
string
The Base64 (URL Safe) encoded design URN.
referencesPayload
SpecifyReferencesPayload
region
Region
Specifies the data center where the manifest and derivatives of the specified source design are stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for the European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note: Beta features are subject to change. Please avoid using them in production environments. (optional)
throwOnError
bool
Returns
Task of SpecifyReferences
Exceptions
Thrown when an API call fails.
StartJobAsync(string, JobPayload, Region, bool, XAdsDerivativeFormat, bool)
Operation: Create Translation Job
Creates a job to translate the specified source design to another format, generating derivatives of the source design. You can optionally:
- Extract selected parts of a design and export the set of geometries in OBJ format.
- Generate different-sized thumbnails.
When the translation job runs, details about the process and generated derivatives are logged to a JSON file known as a manifest. This manifest is typically created during the first translation of a source design. Subsequently, the system updates the same manifest whenever a translation is performed for that design.
If necessary, you can set the x-ads-force
parameter to true
. Then, the system will delete the existing manifest and create a new one. However, be aware that doing so will also delete all previously generated derivatives.
public Task<Job> StartJobAsync(string accessToken, JobPayload jobPayload, Region region = Region.US, bool xAdsForce = false, XAdsDerivativeFormat xAdsDerivativeFormat = XAdsDerivativeFormat.Latest, bool throwOnError = true)
Parameters
accessToken
string
An access token obtained by a call to GetThreeLeggedTokenAsync() or GetTwoLeggedTokenAsync().
jobPayload
JobPayload
region
Region
Specifies the data center where the manifest and derivatives must be stored. Possible values are:
US
- (Default) Data center for the US region.EMEA
- Data center for European Union, Middle East, and Africa.APAC
- (Beta) Data center for the Australia region.
Note:
- Beta features are subject to change. Please avoid using them in production environments.
- Calling this operation twice for the same source design with different values for this parameter creates two distinct sets of manifests and derivatives. Each set is stored in the respective region. (optional)
xAdsForce
bool
true
: Forces the system to parse property data all over again. Use this option to retrieve an object tree when previous attempts have failed.
false
: (Default) Use previously parsed property data to extract the object tree. (optional)
xAdsDerivativeFormat
XAdsDerivativeFormat
Specifies what Object IDs to return, if the design has legacy SVF derivatives generated by the BIM Docs service. Possible values are:
latest
- (Default) Return SVF2 Object IDs.fallback
- Return SVF Object IDs.
Note:
- This parameter applies only to designs with legacy SVF derivatives generated by the BIM 360 Docs service.
- The BIM 360 Docs service now generates SVF2 derivatives. SVF2 Object IDs may not be compatible with the SVF Object IDs previously generated by the BIM 360 Docs service. Setting this parameter to fallback may resolve backward compatibility issues resulting from Object IDs of legacy SVF derivatives being retained on the client side.
- If you use this parameter with one derivative (URN), you must use it consistently across the following:
- Create Translation Job (for OBJ output)
- Fetch Object Tree
- Fetch All Properties (optional)
throwOnError
bool
Returns
Task of Job
Exceptions
Thrown when an API call fails.