docs/Tutorials/03. Explore Versions Item and Derivative Urn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Autodesk Forge is a collection of Autodesk's cloud-based APIs and services. It allows developers to create applications that can interact with Autodesk's software and services in a cloud-based environment. \n",
    "\n",
    "One of the key components of Autodesk Forge is the \"Version\" item. In the context of Autodesk Forge, a \"Version\" represents a specific iteration of a design file. Each time a design file is updated and saved, a new version is created. This allows for tracking of changes and the ability to revert to previous versions if necessary.\n",
    "\n",
    "The Version item in Autodesk Forge includes several properties:\n",
    "\n",
    "- `id`: A unique identifier for the version.\n",
    "- `type`: The type of the item, which is \"versions\" for version items.\n",
    "- `attributes`: This includes several sub-properties like `name` (the name of the version), `createTime` (when the version was created), `createUserId` (the user who created the version), `lastModifiedTime` (when the version was last modified), and `versionNumber` (the version number).\n",
    "\n",
    "To interact with the Version item, Autodesk Forge provides several APIs, including:\n",
    "\n",
    "- Versions API: Allows you to get metadata about a specific version, get a list of versions for a specific item, and upload a new version of a design file.\n",
    "- Data Management API: Allows you to manage and access data across BIM 360 Team, Fusion Team, BIM 360 Docs, A360 Personal, and the Object Storage Service.\n",
    "\n",
    "Remember, to use these APIs, you need to authenticate your application with Autodesk Forge's OAuth service."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><div></div><div></div><div><strong>Installed Packages</strong><ul><li><span>APSToolkit, 1.0.8-beta</span></li></ul></div></div>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "Loading extensions from `C:\\Users\\chuongho\\.nuget\\packages\\microsoft.data.analysis\\0.21.1\\interactive-extensions\\dotnet\\Microsoft.Data.Analysis.Interactive.dll`"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "#r \"nuget:APSToolkit , 1.0.8-beta\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [],
   "source": [
    "using APSToolkit;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Auth"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [],
   "source": [
    "using APSToolkit.Auth;\n",
    "// Get 2-legged token\n",
    "var token = Authentication.Get2LeggedToken().Result;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Version Items"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=28\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=27\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=26\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=25\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=24\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=23\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=22\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=21\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=20\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=19\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=18\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=17\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=16\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=15\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=14\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=13\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=12\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=11\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=10\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=9\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=8\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=7\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=6\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=5\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=4\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=3\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=2\n",
      "Item Version: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=1\n"
     ]
    }
   ],
   "source": [
    "using APSToolkit.BIM360;\n",
    "string itemId = \"urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA\";\n",
    "string projectId = \"b.ca790fb5-141d-4ad5-b411-0461af2e9748\";\n",
    "var bim360 = new BIM360(token);\n",
    "var itemVersions = bim360.GetItemVersions(projectId, itemId);\n",
    "foreach (var itemVersion in itemVersions)\n",
    "{\n",
    "    dynamic itemVersionw = itemVersion.Value;\n",
    "    Console.WriteLine(\"Item Version: \" + itemVersionw.id);\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Latest Version of an Item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Latest Item Version Id: urn:adsk.wipprod:fs.file:vf.Od8txDbKSSelToVg1oc1VA?version=28\r\n"
     ]
    }
   ],
   "source": [
    "var latestItem = bim360.GetLatestVersionItem(projectId, itemId);\n",
    "Console.WriteLine(\"Latest Item Version Id: \" + latestItem.id);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## URN"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Autodesk Forge, a URN (Uniform Resource Name) is a unique identifier for a specific resource, such as a design file or version of a file. \n",
    "\n",
    "A derivative, on the other hand, is a representation of a design file in a different format. For example, a 3D model might have derivatives that are 2D drawings, thumbnail images, or files in different 3D formats. \n",
    "\n",
    "When you upload a design file to Autodesk Forge, it creates a URN for that file and generates derivatives. These derivatives are also associated with their own unique URNs. \n",
    "\n",
    "You can use these URNs to retrieve specific resources through the Forge APIs. For example, you might retrieve a derivative to display a 3D model in a web browser, or to download a 2D drawing. \n",
    "\n",
    "In summary, a URN derivative in Autodesk Forge is a unique identifier for a specific representation of a design file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Derivative Urn: dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yOA\r\n"
     ]
    }
   ],
   "source": [
    "string itemId = \"urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA\";\n",
    "int version = 28;\n",
    "var derivativeUrn = bim360.GetDerivativesUrn(projectId, itemId, version);\n",
    "Console.WriteLine(\"Derivative Urn: \" + derivativeUrn);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Generate Report URN By ItemId"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "dotnet_interactive": {
     "language": "csharp"
    },
    "polyglot_notebook": {
     "kernelName": "csharp"
    },
    "vscode": {
     "languageId": "polyglot-notebook"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<table id=\"table_638447523499776800\"><thead><tr><th><i>index</i></th><th>ItemId</th><th>Version</th><th>URN</th><th>LastModifiedTime</th></tr></thead><tbody><tr><td><i><div class=\"dni-plaintext\"><pre>0</pre></div></i></td><td>urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA</td><td>28</td><td>dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yOA</td><td>2/22/2024 3:40:47 AM</td></tr><tr><td><i><div class=\"dni-plaintext\"><pre>1</pre></div></i></td><td>urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA</td><td>27</td><td>dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yNw</td><td>2/22/2024 3:24:11 AM</td></tr><tr><td><i><div class=\"dni-plaintext\"><pre>2</pre></div></i></td><td>urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA</td><td>26</td><td>dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yNg</td><td>2/22/2024 2:21:53 AM</td></tr><tr><td><i><div class=\"dni-plaintext\"><pre>3</pre></div></i></td><td>urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA</td><td>25</td><td>dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yNQ</td><td>2/21/2024 3:13:36 AM</td></tr><tr><td><i><div class=\"dni-plaintext\"><pre>4</pre></div></i></td><td>urn:adsk.wipprod:dm.lineage:Od8txDbKSSelToVg1oc1VA</td><td>24</td><td>dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLk9kOHR4RGJLU1NlbFRvVmcxb2MxVkE_dmVyc2lvbj0yNA</td><td>2/21/2024 2:34:14 AM</td></tr></tbody></table><style>\r\n",
       ".dni-code-hint {\r\n",
       "    font-style: italic;\r\n",
       "    overflow: hidden;\r\n",
       "    white-space: nowrap;\r\n",
       "}\r\n",
       ".dni-treeview {\r\n",
       "    white-space: nowrap;\r\n",
       "}\r\n",
       ".dni-treeview td {\r\n",
       "    vertical-align: top;\r\n",
       "    text-align: start;\r\n",
       "}\r\n",
       "details.dni-treeview {\r\n",
       "    padding-left: 1em;\r\n",
       "}\r\n",
       "table td {\r\n",
       "    text-align: start;\r\n",
       "}\r\n",
       "table tr { \r\n",
       "    vertical-align: top; \r\n",
       "    margin: 0em 0px;\r\n",
       "}\r\n",
       "table tr td pre \r\n",
       "{ \r\n",
       "    vertical-align: top !important; \r\n",
       "    margin: 0em 0px !important;\r\n",
       "} \r\n",
       "table th {\r\n",
       "    text-align: start;\r\n",
       "}\r\n",
       "</style>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using APSToolkit.Utils;\n",
    "var dt = bim360.BatchReportItemVersions(projectId, itemId);\n",
    "var df = dt.ToDataFrame();\n",
    "df.Head(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What you can do with a URN:\n",
    "- Get the metadata of a specific item\n",
    "- Get the metadata of a specific version\n",
    "- Export data to different formats\n",
    "- Query the properties of a specific item\n",
    "...\n",
    "\n",
    "Congratulations! You have learned the basics of the Autodesk Platform Services API about `Version Item` and `URN`. Now you can continute for the next part to learn how to use the APIs to use `item` and `urn` with another task."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}