Request

Response

    Access M&E Data Model Asset Metadata

    This tutorial walks you through the steps to access asset metadata in the Autodesk cloud using the M&E Data Model API. You will learn how to:

    • Access collections (hubs) to find the collection ID. - Find the project ID within a collection. - Query a project for its metadata. - Query for assets within a project. - Query for the binary components of an asset.

    This walkthrough shows queries, inputs and responses in GraphQL as they appear in M&E Data Model Explorer. To follow this, you will need to be logged in with your Autodesk account on this system.

    Step 1: Access Collections

    Collections (also called “hubs”) are the top-level containers in the Autodesk cloud. To get a list of all the collections you have access to, make a GraphQL request using the collections query. The response will include the collection ID, which you will need for subsequent steps.

    Usage Note: You can either paste the operations below into a new tab in M&E Data Model Explorer, or build a matching query using the “Documentation Explorer” tab, which lists available queries and their parameters.

    Query

    query Query {
      collections {
        ... on CollectionsResponse {
          data {
            id
          }
        }
      }
    }
    
    Show More

    Query Variables

    In the Variables panel, you can also specify any relevant input parameters for the query. For example you can use this to set the pagination limit on the list of results returned.

    {
      "input": {
        "pagination": {
          "limit": 5
        }
      }
    }
    

    Response

    {
      "data": {
        "collections": {
          "data": [
            {
              "id": "<YOUR_COLLECTION_ID>"
            }
          ]
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 12
        }
      }
    }
    
    Show More

    The collections array contains a list of collections you have access to (typically most users have access to a single collection). Find the collection you want to work with, and note the collection ID (<YOUR_COLLECTION_ID>).

    The extensions.pointValue.requestedQueryPointValue field indicates the point value of the query. The point value is a measure of the complexity of the query and is used to enforce rate limits. For more information, see Rate Limits.

    If there is an error the response will contain a developerMessage and errorCode. For example:

    {
      "developerMessage": "Access token provided is invalid or expired.",
      "moreInfo": "https://forge.autodesk.com/en/docs/oauth/v2/developers_guide/error_handling/",
      "errorCode": "AUTH-006"
    }
    

    In this case the access token has expired and needs to be refreshed.

    Note: You are unlikely to see this error in the M&E Data Model Explorer, as it automatically refreshes the access token when it expires. However, if you are using a custom application, you will need to handle this error and refresh the access token as needed.

    Step 2: Find the Project ID

    To get a list of all the projects in the collection, use the projects query.

    Query

    query Projects($input: GetProjectsInput!) {
      projects(input: $input) {
        ... on ProjectsResponse {
          data {
            description
            id
            name
          }
        }
      }
    }
    
    Show More

    Query Variables

    {
      "input": {
        "collectionId": "<YOUR_COLLECTION_ID>",
      }
    }
    

    Response

    {
      "data": {
        "projects": {
          "data": [
            {
              "description": "",
              "id": "<YOUR_PROJECT_ID>",
              "name": "Toy Story 5"
            },
            {
              "description": "",
              "id": "<YOUR_PROEJCT_ID2>",
              "name": "RobotAdventures"
            }
          ]
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 12
        }
      }
    }
    
    Show More

    Optional: Query Project Metadata

    You can use the project query to get metadata about a specific project, such as the project name, description, and its components

    Request

    query Project($projectId: ID!) {
      project(id: $projectId) {
        ... on Project {
          name
          description
          components {
            data
          }
        }
      }
    }
    
    Show More

    Input

    {
      "projectId": "<YOUR_PROJECT_ID>"
    }
    

    Response

    {
      "data": {
        "project": {
          "name": "Sequence with cuts",
          "description": "",
          "components": [
            {
              "data": {
                "id": "urn:shotgrid:asset:403031|shotgrid-cxd02.dev.shotgrid.autodesk.com|556"
              }
            }
          ]
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 2
        }
      }
    }
    
    Show More

    Step 3: Find Assets

    To get a list of assets in a project, use the assets query. This query should use pagination, as a query that returns a large number of assets can time out.

    Query

    query Assets($input: FindAssetsInput!) {
      assets(input: $input) {
        ... on AssetsResponse {
          data {
            id
            name
          }
          pagination {
            cursor
            pageSize
          }
        }
      }
    }
    
    Show More

    Query Variables

    {
      "input": {
        "projectId": "<YOUR_PROJECT_ID>",
        "pagination": {
          "cursor": "",
          "limit": 10
        }
      }
    }
    
    Show More

    Response

    {
      "data": {
        "assets": {
          "data": [
            {
              "id": "<ID>",
              "name": "Shots"
            },
            {
              "id": "<ID>",
              "name": "Cuts"
            },
            {
              "id": "<ID>",
              "name": "Media"
            }
          ],
          "pagination": {
            "cursor": "52355966504252494c45464336786841637071446f792d32",
            "pageSize": 3
          }
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 13
        }
      }
    }
    
    Show More

    Here we set the cursor size to 3, but the response may contain a smaller or larger number of assets due to query optimization. The actual number returned is in the pagination.pageSize field. Use the returned cursor string in subsequent queries to retrieve the next page of assets.

    Step 4: Get Asset Details

    To get details about a specific asset, use the asset query. This query requires the asset ID, which you can obtain from the previous step.

    Query

    query Asset($input: GetAssetInput) {
      asset(input: $input) {
        ... on Asset {
          description
          hasChildren
          id
          name
          path {
            ... on AssetPathResponse {
              data {
                ... on Project {
                  description
                  name
                }
              }
            }
          }
          revisionId
          version
          components {
            name
            typeId
            typeName
            data
          }
        }
      }
    }
    
    Show More

    Query Variables

    {
      "input": {
        "id": "<YOUR_ASSET_ID>"
      }
    }
    

    Response

    {
      "data": {
        "asset": {
          "description": "",
          "hasChildren": true,
          "id": "<YOUR_ASSET_ID>",
          "name": "Media",
          "path": {
            "data": [
              {
                "description": "",
                "name": "Sequence with cuts"
              },
              {}
            ]
          },
          "revisionId": "<REVISION_ID>",
          "version": 0,
          "components": [
            {
              "name": "folder",
              "typeId": "autodesk.me:type.folder-1.0.0"
              "typeName": "type.folder",
              "data": {
                "data": [],
                "purpose": ""
              }
            }
          ]
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 14
        }
      }
    }
    
    Show More

    In this response, we see various asset details, including the asset ID, name, description, and components. The components field indicates that this asset is a folder, and the hasChildren field indicates that it contains other assets.

    Step 5: Fetch Binary Component Urls

    To get the binary component urls for a specific asset, first get the URN of a binary component you want to fetch. Not all assets will have binary components, so you will need to check the components field in the asset details response. If the asset has a binary component, it will have a typeName of component.binary. The urn will be in the component’s data field.

    You can use the asset query to get the details of a component.binary type asset, including its binary paths, which are returned as URNs. Pass the ID of the asset as the input.

    query Asset($input: GetAssetInput) {
      asset(input: $input) {
        ... on Asset {
          path {
            ... on AssetPathResponse {
              data {
                ... on Asset {
                  description
                  name
                  path {
                    ... on AssetPathResponse {
                      data {
                        ... on Project {
                          components {
                            data
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
    
    Show More

    The reponse will contain the URN of the binary component in the components.data field. The remainder of this response is omitted for clarity.

    {
      "data": {
        "asset": {
          "path": {
            "data": [
              {},
              {
                "description": "",
                "name": "Shots",
                "path": {
                  "data": [
                    {
                      "components": [
                        {
                          "data": {
                            "id": "<URN_OF_BINARY_COMPONENT>"
                          }
                        }
                      ]
                    },
                    ...
    
    }
    
    Show More

    Once you have one or more URNs to fetch, you can use the fetchBinaryComponentsUrls query to get the URLs for those components.

    Query

    query FetchBinaryComponentsUrls($input: FetchBinaryComponentUrlsInput!) {
      fetchBinaryComponentsUrls(input: $input) {
        urls {
          url
        }
      }
    }
    

    Query Variables

    {
      "input": {
        "collectionId": "<YOUR_COLLECTION_ID>",
        "urns": ["<YOUR_BINARY_COMPONENT_URN>"]
      }
    }
    

    Response

      "data": {
        "fetchBinaryComponentsUrls": {
          "urls": ["<YOUR_BINARY_COMPONENT_URL>"],
          "urlErrors": []
        }
      },
      "extensions": {
        "pointValue": {
          "requestedQueryPointValue": 13
        }
      }
    }
    
    Show More