.. Warning: this file is automatically generated. Edits will be lost .. list-table:: Functions defined in :mod:`CNRead` :widths: 3 3 10 10 30 :header-rows: 1 * - Tier - Version - REST - Function - Parameters * - Tier 1 - 1.0, 2.0 - ``GET /object/{id}`` - :func:`get` - (:class:`session`, :class:`id`) ``->`` :class:`Types.OctetStream` * - Tier 1 - 1.0, 2.0 - ``GET /meta/{id}`` - :func:`getSystemMetadata` - (:class:`session`, :class:`id`) ``->`` :class:`Types.SystemMetadata` * - Tier 1 - 1.0, 2.0 - ``HEAD /object/{id}`` - :func:`describe` - (:class:`session`, :class:`id`) ``->`` :class:`Types.DescribeResponse` * - Tier 1 - 1.0, 2.0 - ``GET /resolve/{id}`` - :func:`resolve` - (:class:`session`, :class:`id`) ``->`` :class:`Types.ObjectLocationList` * - Tier 1 - 1.0, (2.0) - ``GET /checksum/{pid}`` - :func:`getChecksum` - (:class:`session`, :class:`pid`) ``->`` :class:`Types.Checksum` * - Tier 1 - 1.0, (2.0) - ``GET /object[?fromDate={fromDate}&toDate={toDate}&identifier={identifier}&formatId={formatId}&nodeId={nodeId}&start={start}&count={count}]`` - :func:`listObjects` - (:class:`session`, :class:`[fromDate]`, :class:`[toDate]`, :class:`[formatId]`, :class:`[identifier]`, ``[start=0]``, ``[count=1000]``, :class:`[nodeId]`) ``->`` :class:`Types.ObjectList` * - Tier 1 - 1.0, (2.0) - ``GET /search/{queryType}/{query}`` - :func:`search` - (:class:`session`, ``queryType``, ``query``) ``->`` :class:`Types.ObjectList` * - Tier 1 - 1.1, (2.0) - ``GET /query/{queryEngine}/{query}`` - :func:`query` - (:class:`session`, ``queryEngine``, ``query``) ``->`` :class:`Types.OctetStream` * - Tier 1 - 1.1, (2.0) - ``GET /query/{queryType}`` - :func:`getQueryEngineDescription` - (:class:`session`, ``queryEngine``) ``->`` :class:`Types.QueryEngineDescription` * - Tier 1 - 1.1, (2.0) - ``GET /query`` - :func:`listQueryEngines` - (:class:`session`) ``->`` :class:`Types.QueryEngineList` * - Tier 1 - 2.0 - ``POST /synchronize`` - :func:`synchronize` - (:class:`session`, :class:`pid`) ``->`` boolean .. function:: get(session,id) -> OctetStream Retrieves the object identified by *id* from the node. If the object is not present on the node, then an :exc:`Exceptions.NotFound` error is raised, regardless of whether the object exists on another node in the DataONE system. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. :Version: 1.0, 2.0 :Use Cases: :doc:`UC01 `, :doc:`UC16 `, :doc:`UC09 ` :REST URL: ``GET /object/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: Identifier of the object to be retrieved. May be either a PID or a SID, the latter acting as if called using the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: For science metadata objects, this will be the exact byte stream of the science metadata object as it was original ingested. Note that additional object types may in the future be returned by the get method. :rtype: :class:`Types.OctetStream` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1000)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1001)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=1020)`` The object specified by the identifier is not present on this (or any) CN. The response body should contain a reference to :func:`CNRead.resolve`. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1030)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1010)`` .. include:: /apis/examples/cn_get.txt .. function:: getSystemMetadata(session,id) -> SystemMetadata Returns the :term:`system metadata` that contains DataONE specific information about the object identified by *id*. Authoritative copies of system metadata are only available from the Coordinating Nodes. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID` and the returned :class:`v2_0.Types.SystemMetadata` structure has changed. :Version: 1.0, 2.0 :Use Cases: :doc:`UC36 `, :doc:`UC37 `, :doc:`UC16 ` :REST URL: ``GET /meta/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: Identifier for the object of interest. May be either a PID or a SID, the latter acts as if called with the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: A system metadata document describing the object. :rtype: :class:`Types.SystemMetadata` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1050)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1041)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1090)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1040)`` The principal identified by token does not have READ permission on the object. :raises Exceptions.NotFound: ``(errorCode=404, detailCode=1060)`` There is no object identified by *pid* and so no system metadata can be returned. .. include:: /apis/examples/cn_getSystemMetadata.txt .. function:: describe(session,id) -> DescribeResponse This method provides a lighter weight mechanism than :func:`CNRead.getSystemMetadata` for a client to determine basic properties of the referenced object. The response should indicate properties that are typically returned in a HTTP HEAD request: the date late modified, the size of the object, the type of the object (the :attr:`SystemMetadata.formatId`). The principal indicated by *token* must have read privileges on the object, otherwise :exc:`Exceptions.NotAuthorized` is raised. If the object does not exist on the node servicing the request, then :exc:`Exceptions.NotFound` must be raised even if the object exists on another node in the DataONE system. Note that this method is likely to be called frequently and so efficiency should be taken into consideration during implementation. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. :Version: 1.0, 2.0 :Use Cases: :doc:`UC16 ` :REST URL: ``HEAD /object/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: Identifier for the object in question. May be either a PID or a SID, the latter acting as if called with the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: A set of values providing a basic description of the object. :rtype: :class:`Types.DescribeResponse` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4930)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4931)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4932)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4933)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4934)`` .. include:: /apis/examples/describe.txt .. function:: resolve(session,id) -> ObjectLocationList Returns a list of nodes (MNs or CNs) known to hold copies of the object identified by *id*. The object resolution process is intended to provide a simple mechanism for a client to discover from which node(s) a particular object may be retrieved. Details about method interfaces (i.e. REST URLs) exposed by a particular node can be determined by examining the response from the *node* collection. For convenience, the :func:`MNRead.get` URL is included in the response as is the base URL of the node REST services. Note also that the same functionality as *resolve()* can be implemented by retrieving a copy of the system metadata for the object and utilizing the node registry to discover the base URL from which the client can construct the *get()* URL. Resolve is provided for efficiency since the response size is much smaller. Resolve will return a HTTP status of 303 (see other) on success. The HTTP header "Location" MUST be set, and it's value SHOULD be the full get() URL for retrieving the object from the first location in the resolve response. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. If the identifier is a SID, then resolution is for the latest version of an object (i.e. the head of the obsolescence chain). :Version: 1.0, 2.0 :Use Cases: :doc:`UC36 `, :doc:`UC16 ` :REST URL: ``GET /resolve/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: Identifier being resolved. May be either a PID or a SID, the latter acting as if called with the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: A list of nodes known to contain copies of the target object, plus the URLs known to resolve to the node get methods. :rtype: :class:`Types.ObjectLocationList` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4130)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4150)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4120)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4140)`` There is no object identified by the given identifier :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4131)`` .. include:: /apis/examples/resolve.txt .. function:: getChecksum(session,pid) -> Checksum Returns the checksum for the specified object as reported in the system metadata. Note that the signature of this method differs from :func:`MNRead.getChecksum` as that method takes an optional algorithm parameter. :Version: 1.0, (2.0) :Use Cases: :doc:`UC09 ` :REST URL: ``GET /checksum/{pid}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: Identifier of the object for which checksum is being requested Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :returns: The checksum of the specified object :rtype: :class:`Types.Checksum` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1402)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1410)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=1420)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1400)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1430)`` .. function:: listObjects(session,[fromDate],[toDate],[formatId],[identifier],[start=0],[count=1000],[nodeId]) -> ObjectList Retrieve the list of objects present on the CN that match the calling parameters. At a minimum, this method should be able to return a list of objects that match:: fromDate < SystemMetadata.dateSysMetadataModified but is expected to also support date range (by also specifying *toDate*), and should also support slicing of the matching set of records by indicating the starting *index* of the response (where 0 is the index of the first item) and the *count* of elements to be returned. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. V2.0: Added filter on authoritativeMemberNode value. :Version: 1.0, (2.0) :Use Cases: :doc:`UC06 `, :doc:`UC16 ` :REST URL: ``GET /object[?fromDate={fromDate}&toDate={toDate}&identifier={identifier}&formatId={formatId}&nodeId={nodeId}&start={start}&count={count}]`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param fromDate: Entries with :attr:`SystemMetadata.dateSysMetadataModified` greater than or equal to (>=) *fromDate* must be returned. Transmitted as a URL query parameter, and so must be escaped accordingly. :type fromDate: :class:`Types.DateTime` :param toDate: Entries with :attr:`SystemMetadata.dateSysMetadataModified` less than (<) *toDate* must be returned. Transmitted as a URL query parameter, and so must be escaped accordingly. :type toDate: :class:`Types.DateTime` :param formatId: Restrict results to the specified object format. Transmitted as a URL query parameter, and so must be escaped accordingly. :type formatId: :class:`Types.ObjectFormatIdentifier` :param identifier: Restrict results to the specified identifier. May be either a PID or a SID. If the latter, will return results for each PID in the series. Transmitted as a URL query parameter, and so must be escaped accordingly. :type identifier: :class:`Types.Identifier` :param start=0: The zero-based index of the first value, relative to the first record of the resultset that matches the parameters. Transmitted as a URL query parameter, and so must be escaped accordingly. :type start=0: integer :param count=1000: The maximum number of entries that should be returned in the response. The Member Node may return fewer and the caller should check the *total* in the response to determine if further pages may be retrieved. Transmitted as a URL query parameter, and so must be escaped accordingly. :type count=1000: integer :param nodeId: Restrict results to those with authoritativeMemberNode equal to nodeId. Transmitted as a URL query parameter, and so must be escaped accordingly. :type nodeId: :class:`Types.NodeReference` :returns: The list of PIDs that match the query criteria. If none match, an empty list is returned. :rtype: :class:`Types.ObjectList` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1520)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=1540)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1560)`` Raised if some functionality requested is not implemented. In the case of an optional request parameter not being supported, the errorCode should be 400. If the requested format (through HTTP Accept headers) is not supported, then the standard HTTP 406 error code should be returned. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1580)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1530)`` .. function:: search(session,queryType,query) -> ObjectList Search the metadata catalog and return identifiers of metadata records that match the criteria. Search may be implemented by more than one type of search engine. The queryType parameter indicates which search engine should be targeted. The value and form of *query* is determined by the search engine. Currently supported search engines include: "solr" :Version: 1.0, (2.0) :Use Cases: :doc:`UC02 `, :doc:`UC16 ` :REST URL: ``GET /search/{queryType}/{query}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param queryType: Indicates which search engine will be used to handle the query. Currently supported search engines include: "SOLR". Transmitted as part of the URL path and must be escaped accordingly. :type queryType: string :param query: The remainder of the URL is passed verbatim to the respective search engine implementation. Hence it may contain additional path elements and query elements as determined by the functionality of the search engine. The caller is reponsible for providing a '?' to indicate the start of the query string portion of the URL, as well as proper URL escaping. Transmitted as part of the URL path and must be escaped accordingly. :type query: string :returns: A list of objects that match the specified search criteria :rtype: :class:`Types.ObjectList` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4290)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4310)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4280)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4300)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4281)`` .. function:: query(session,queryEngine,query) -> OctetStream Submit a query against the specified *queryEngine* and return the response as formatted by the queryEngine. The *query()* operation may be implemented by more than one type of search engine and the *queryEngine* parameter indicates which search engine is targeted. The value and form of *query* is determined by the specific query engine. For example, the solr search engine will accept many of the standard parameters of solr, including field restrictions and faceting. v1.1: This method was added. :Version: 1.1, (2.0) :Use Cases: :doc:`UC02 `, :doc:`UC16 ` :REST URL: ``GET /query/{queryEngine}/{query}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param queryEngine: Indicates which search engine will be used to handle the query. Supported search engines can be determined through the CNRead.listQueryEngines API call. Transmitted as part of the URL path and must be escaped accordingly. :type queryEngine: string :param query: The remainder of the URL is passed verbatim to the respective search engine implementation. Hence it may contain additional path elements and query elements as determined by the functionality of the search engine. The caller is reponsible for providing a '?' to indicate the start of the query string portion of the URL, as well as proper URL escaping. Transmitted as part of the URL path and must be escaped accordingly. :type query: string :returns: The structure of the response is determined by the chosen search engine and parameters provided to it. :rtype: :class:`Types.OctetStream` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4320)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4321)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4322)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4323)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4324)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4325)`` The specified queryEngine does not exist .. function:: getQueryEngineDescription(session,queryEngine) -> QueryEngineDescription Provides metadata about the query service of the specified *queryEngine*. The metadata provides a brief description of the query engine, its version, its schema version, and an optional list of fields supported by the query engine. v1.1: This method was added. :Version: 1.1, (2.0) :REST URL: ``GET /query/{queryType}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate provided with the request. The certificate must be traceable to an authority recognized by DataONE, currently CILogon. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param queryEngine: Indicates which query engine for which to provide descriptive metadata. Currently supported search engines can be determined through CNRead.listQueryEngines. Transmitted as part of the URL path and must be escaped accordingly. :type queryEngine: string :returns: A list of fields that are supported by the search index and additional metadata. :rtype: :class:`Types.QueryEngineDescription` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4410)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4411)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4412)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4413)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4414)`` The specified queryEngine does not exist .. function:: listQueryEngines(session) -> QueryEngineList Returns a list of query engines, i.e. supported values for the *queryEngine* parameter of the *getQueryEngineDescription* and *query* operations. The list of search engines available may be influenced by the authentication status of the request. v1.1: This method was added. :Version: 1.1, (2.0) :REST URL: ``GET /query`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate provided with the request. The certificate must be traceable to an authority recognized by DataONE, currently CILogon. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :returns: A list of names of queryEngines available to the user identified by *session*. :rtype: :class:`Types.QueryEngineList` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4420)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4421)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4422)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4423)`` .. function:: synchronize(session,pid) -> boolean Indicates to the CN that a new or existing object identified by PID requires synchronization. Note that this operation is asynchronous, a successful return indicates that the synchronization task was successfully queued. This method may be called by any Member Node for new content or the authoritative Member Node for updates to existing content. The CN will schedule the synchronization task which will then be processed in the same way as content changes identified through the listObjects polling mechanism. v2.0: This method was added to the Version 2.0 API. :Version: 2.0 :REST URL: ``POST /synchronize`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type pid: :class:`Types.Identifier` :returns: True if the synchronization request was successfully queued, otherwise False :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4960)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4961)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4962)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4963)``