Merge pull request #38 from opencloud-eu/feat/download-url

feat: Add @microsoft.graph.downloadUrl annotation and /content endpoi…

Author: micbar

api/openapi-spec/v1.0.yaml

@@ -1206,6 +1206,7 @@ paths:
             type: string
           example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id
           x-ms-docs-key-type: item
+        - $ref: '#/components/parameters/driveItemSelect'
       responses:
         "200":
           description: Retrieved driveItem
@@ -1309,6 +1310,64 @@ paths:
         default:
           $ref: '#/components/responses/error'
       x-ms-docs-operation-type: operation
+  '/v1beta1/drives/{drive-id}/items/{item-id}/content':
+    get:
+      tags:
+        - driveItem
+      summary: Download the content of a DriveItem
+      operationId: GetDriveItemContent
+      description: |
+        Download the contents of the primary stream (file) of a driveItem. Only
+        driveItem objects with a `file` facet can be downloaded.
+
+        The response is a `302 Found` redirecting to a pre-authenticated download
+        URL for the file. This is the same URL that is returned via the
+        `@microsoft.graph.downloadUrl` instance annotation on the driveItem when
+        requested via `$select`. Choose between the two based on whether you
+        want to call the redirecting `/content` endpoint directly (for example,
+        with a client that follows redirects automatically) or you want to
+        inspect / schedule / prefetch the URL yourself via the annotation.
+
+        The pre-authenticated URL is short-lived and does not require an
+        `Authorization` header.
+
+        To download a partial range of bytes, apply the `Range` header to the
+        redirect target (the pre-authenticated URL), not to the `/content`
+        request.
+      parameters:
+        - name: drive-id
+          in: path
+          description: 'key: id of drive'
+          required: true
+          schema:
+            type: string
+          x-ms-docs-key-type: drive
+        - name: item-id
+          in: path
+          description: 'key: id of item'
+          required: true
+          schema:
+            type: string
+          x-ms-docs-key-type: item
+      responses:
+        '302':
+          description: Pre-authenticated redirect to the file content.
+          headers:
+            Location:
+              required: true
+              schema:
+                type: string
+                format: uri
+              description: The pre-authenticated URL where the content can be downloaded.
+        '404':
+          description: The driveItem was not found or is not a file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/odata.error'
+        default:
+          $ref: '#/components/responses/error'
+      x-ms-docs-operation-type: operation
   '/v1beta1/drives/{drive-id}/items/{item-id}/createLink':
     post:
       tags:
@@ -4917,6 +4976,16 @@ components:
         '@client.synchronize':
           description: Indicates if the item is synchronized with the underlying storage provider. Read-only.
           type: boolean
+        '@microsoft.graph.downloadUrl':
+          description: |
+            A pre-authenticated URL that can be used to download the item's content without
+            providing an Authorization header. The URL is short-lived and cannot be cached.
+
+            This annotation is only populated when explicitly requested via `$select`, and
+            only for items that have a `file` facet. The returned URL is valid for a
+            limited time and should be used promptly.
+          type: string
+          readOnly: true
         # follows the SAP UI vocabulary: https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/UI.md
         '@UI.Hidden':
           description: Properties or facets (see UI.Facet) annotated with this term will not be rendered if the annotation evaluates to true. Users can set this to hide permissions.
@@ -5915,6 +5984,23 @@ components:
       description: Search items by search phrases
       schema:
         type: string
+    driveItemSelect:
+      name: $select
+      in: query
+      description: Select additional properties to be returned.
+      style: form
+      explode: false
+      schema:
+        uniqueItems: true
+        type: array
+        items:
+          enum:
+            - '@microsoft.graph.downloadUrl'
+          type: string
+      examples:
+        request download url:
+          value:
+            - '@microsoft.graph.downloadUrl'
     drivesFilter:
       name: $filter
       in: query