DescribeStream

On This Page

Description

Retrieves a stream’s configuration, including the shard count and retention period.

Request

Request Header

Syntax
    POST /<container>/<resource> HTTP/1.1
    Host: <web-APIs URL>
    Content-Type: application/json
    X-v3io-function: DescribeStream
    <Authorization OR X-v3io-session-key>: <value>
    
    url = "http://<web-APIs URL>/<container>/<resource>"
    headers = {
                "Content-Type": "application/json",
                "X-v3io-function": "DescribeStream",
                "<Authorization OR X-v3io-session-key>": "<value>"
              }
    
    URL Resource Parameters

    The path to the target stream. You can optionally set the stream name in the request’s StreamName JSON parameter instead of in the URL.

    Request Data

    Syntax
      {
          "StreamName": "string",
      }
      
      payload = {"StreamName": "string"}
      
      Parameters
      StreamName

      The name of the stream for which to retrieve the description.

      • Type: String
      • Requirement: Required if not set in the request URL

      Response

      Response Data

      Syntax
      {
          "ShardCount":            number,
          "RetentionPeriodHours":  number
      }
      
      Elements
      ShardCount

      The steam’s shard count (the total number of shards in the stream).

      • Type: Number
      RetentionPeriodHours

      The stream’s retention period, in hours. After this period elapses, when new records are added to the stream, the earliest ingested records are deleted.

      • Type: Number

      Errors

      In the event of an error, the response includes a JSON object with an ErrorCode element that contains a unique numeric error code, and an ErrorMessage element that contains one of the following API error messages:
      Error Message Description
      InvalidArgumentException A provided request parameter is not valid for this request.
      Permission denied The sender of the request does not have the required permissions to perform the operation.
      ResourceNotFoundException The specified resource does not exist.

      Examples

      Retrieve configuration information for a MyStream stream:

      Request
        POST /mycontainer/MyStream/ HTTP/1.1
        Host: https://default-tenant.app.mycluster.iguazio.com:8443
        Content-Type: application/json
        X-v3io-function: DescribeStream
        X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf
        
        import requests
        
        url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyStream/"
        headers = {
                    "Content-Type": "application/json",
                    "X-v3io-function": "DescribeStream",
                    "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
                  }
        
        response = requests.post(url, headers=headers)
        print(response.text)
        
        
        Response
        HTTP/1.1 200 OK
        Content-Type: application/json
        ...
        
        {
            "RetentionPeriodHours": 1,
            "ShardCount": 1000
        }