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

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table align=\"left\">\n",
    "  <td style=\"text-align: center\">\n",
    "    <a href=\"https://colab.research.google.com/github/chuongmep/aps-toolkit/blob/dev/APSToolkitPython/Tutorials/03.%20Explore%20Versions%20Item%20and%20Derivative%20Urn.ipynb\">\n",
    "      <img src=\"https://cloud.google.com/ml-engine/images/colab-logo-32px.png\" alt=\"Google Colaboratory logo\"><br> Run in Colab\n",
    "    </a>\n",
    "  </td>\n",
    "  <td style=\"text-align: center\">\n",
    "    <a href=\"https://github.com/chuongmep/aps-toolkit/blob/dev/APSToolkitPython/Tutorials/03.%20Explore%20Versions%20Item%20and%20Derivative%20Urn.ipynb\">\n",
    "      <img src=\"https://cloud.google.com/ml-engine/images/github-logo-32px.png\" alt=\"GitHub logo\"><br> View on GitHub\n",
    "    </a>\n",
    "  </td>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table align=\"left\">\n",
    "  <tr>\n",
    "    <td>Author(s)</td>\n",
    "    <td><a href=\"https://github.com/chuongmep\" id=\"author-link\">Chuong Ho</a></td>\n",
    "    <!-- <td><a href=\"<your repo>\" id=\"github-link\">YourName</a></td> -->\n",
    "  </tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:23.417965Z",
     "start_time": "2024-03-02T14:10:20.268605Z"
    }
   },
   "source": [
    "%pip install aps-toolkit --upgrade"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Auth"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:23.422282Z",
     "start_time": "2024-03-02T14:10:23.418981Z"
    }
   },
   "source": [
    "from aps_toolkit import Auth\n",
    "token = Auth().auth2leg()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Auth With Google Colab"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "source": [
    "# from aps_toolkit import Auth\n",
    "# from google.colab import userdata\n",
    "# client_id = userdata.get('APS_CLIENT_ID')\n",
    "# client_secret = userdata.get('APS_CLIENT_SECRET')\n",
    "# auth = Auth(client_id, client_secret)\n",
    "# token = auth.auth2leg()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Items"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "source": [
    "from aps_toolkit import BIM360\n",
    "\n",
    "bim360 = BIM360(token)"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Items By Folder"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "source": [
    "projects_id = \"b.1f7aa830-c6ef-48be-8a2d-bd554779e74b\"\n",
    "folderId = \"urn:adsk.wipprod:fs.folder:co.5ufH-U8yRjaZ-USJxxN_Mw\"\n",
    "\n",
    "contents = bim360.get_folder_contents(projects_id, folderId)\n",
    "itemId = contents[\"data\"][0][\"id\"]\n",
    "itemId"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Item Versions"
   ]
  },
  {
   "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.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:30.219801Z",
     "start_time": "2024-03-02T14:10:29.256730Z"
    }
   },
   "source": [
    "item_versions = bim360.get_item_versions(projects_id, itemId)\n",
    "# get fist version \n",
    "versionId = item_versions[\"data\"][0][\"id\"]\n",
    "versionId"
   ],
   "outputs": []
  },
  {
   "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": "markdown",
   "metadata": {},
   "source": [
    "In code below, the column `derivativeUrn` is the `URN` of the design file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:42.556985Z",
     "start_time": "2024-03-02T14:10:30.220808Z"
    }
   },
   "source": [
    "data_frame = bim360.batch_report_items(projects_id, folderId, \".rvt\", True)\n",
    "data_frame.head()"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we use in the case we need get data for a specific version of a item.\n",
    "In code bellow, the column `derivativeUrn` is the `URN` of the design file by version of the item."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-02T14:10:43.502899Z",
     "start_time": "2024-03-02T14:10:42.557994Z"
    }
   },
   "source": [
    "data_frame_item_versions = bim360.batch_report_item_versions(projects_id, itemId)\n",
    "data_frame_item_versions"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations! You've learned about the key concepts in Autodesk Forge, including Hubs, Projects, Folders, Items, and URNs. These concepts are the building blocks of the Autodesk Forge platform, and understanding them is crucial for working effectively with design data and collaborating with others."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}