feat(document content): support external id and instance id

CHANGELOG.md

@@ -17,6 +17,10 @@ Changes are grouped as follows
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+## [7.70.0] - 2024-11-24
+### Added
+- Documents content endpoint now support external id and instance id.
+
 ## [7.69.0] - 2024-11-23
 ### Added
 - Synthetic Datapoints API has better support for `instance_id`. Previously you had to specify these directly

cognite/client/_api/documents.py

@@ -8,6 +8,7 @@
 from cognite.client._constants import DEFAULT_LIMIT_READ
 from cognite.client.data_classes import filters
 from cognite.client.data_classes.aggregations import AggregationFilter, UniqueResultList
+from cognite.client.data_classes.data_modeling.ids import NodeId
 from cognite.client.data_classes.documents import (
     Document,
     DocumentHighlightList,
@@ -19,6 +20,7 @@
     TemporaryLink,
 )
 from cognite.client.data_classes.filters import _BASIC_FILTERS, Filter, _validate_filter
+from cognite.client.utils._identifier import IdentifierSequence
 
 if TYPE_CHECKING:
     from cognite.client import ClientConfig, CogniteClient
@@ -467,7 +469,12 @@ def aggregate_unique_properties(
             limit=limit,
         )
 
-    def retrieve_content(self, id: int) -> bytes:
+    def retrieve_content(
+        self,
+        id: int | None = None,
+        external_id: str | None = None,
+        instance_id: NodeId | None = None,
+    ) -> bytes:
         """`Retrieve document content <https://developer.cognite.com/api#tag/Documents/operation/documentsContent>`_
 
         Returns extracted textual information for the given document.
@@ -479,7 +486,9 @@ def retrieve_content(self, id: int) -> bytes:
 
 
         Args:
-            id (int): The server-generated ID for the document you want to retrieve the content of.
+            id (int | None): The server-generated ID for the document you want to retrieve the content of.
+            external_id (str | None): External ID
+            instance_id (NodeId | None): Instance ID
 
         Returns:
             bytes: The content of the document.
@@ -492,10 +501,18 @@ def retrieve_content(self, id: int) -> bytes:
                 >>> client = CogniteClient()
                 >>> content = client.documents.retrieve_content(id=123)
         """
-        response = self._do_request("GET", f"{self._RESOURCE_PATH}/{id}/content", accept="text/plain")
+        identifiers = IdentifierSequence.load(ids=id, external_ids=external_id, instance_ids=instance_id).as_singleton()
+        identifier = identifiers.as_dicts()[0]
+        response = self._do_request("POST", f"{self._RESOURCE_PATH}/content", accept="text/plain", json=identifier)
         return response.content
 
-    def retrieve_content_buffer(self, id: int, buffer: BinaryIO) -> None:
+    def retrieve_content_buffer(
+        self,
+        buffer: BinaryIO,
+        id: int | None = None,
+        external_id: str | None = None,
+        instance_id: NodeId | None = None,
+    ) -> None:
         """`Retrieve document content into buffer <https://developer.cognite.com/api#tag/Documents/operation/documentsContent>`_
 
         Returns extracted textual information for the given document.
@@ -507,8 +524,10 @@ def retrieve_content_buffer(self, id: int, buffer: BinaryIO) -> None:
 
 
         Args:
-            id (int): The server-generated ID for the document you want to retrieve the content of.
             buffer (BinaryIO): The document content is streamed directly into the buffer. This is useful for retrieving large documents.
+            id (int | None): The server-generated ID for the document you want to retrieve the content of.
+            external_id (str | None): External ID
+            instance_id (NodeId | None): Instance ID
 
         Examples:
 
@@ -520,8 +539,10 @@ def retrieve_content_buffer(self, id: int, buffer: BinaryIO) -> None:
                 >>> with Path("my_file.txt").open("wb") as buffer:
                 ...     client.documents.retrieve_content_buffer(id=123, buffer=buffer)
         """
+        identifiers = IdentifierSequence.load(ids=id, external_ids=external_id, instance_ids=instance_id).as_singleton()
+        identifier = identifiers.as_dicts()[0]
         with self._do_request(
-            "GET", f"{self._RESOURCE_PATH}/{id}/content", stream=True, accept="text/plain"
+            "POST", f"{self._RESOURCE_PATH}/content", stream=True, accept="text/plain", json=identifier
         ) as response:
             for chunk in response.iter_content(chunk_size=2**21):
                 if chunk:  # filter out keep-alive new chunks

cognite/client/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
-__version__ = "7.69.0"
+__version__ = "7.70.0"
 __api_subversion__ = "20230101"

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "cognite-sdk"
 
-version = "7.69.0"
+version = "7.70.0"
 description = "Cognite Python SDK"
 readme = "README.md"
 documentation = "https://cognite-sdk-python.readthedocs-hosted.com"