Content
- Operators
-
- IAMAccessTokenGenerator: IBM Streams applications using the streamsx.sttgateway can use/invoke this non-main composite to submit, generate and periodically refresh the IAM access token which will be required by the WatsonSTT operator.
- Types
-
- IAMAccessToken: This type represents the data format for the result returned by the IAMAccessTokenGenerator
Composites
composite IAMAccessTokenGenerator(output stream<IAMAccessToken> IamAccessTokenStream)
IBM Streams applications using the streamsx.sttgateway can use/invoke this non-main composite to submit, generate and periodically refresh the IAM access token which will be required by the WatsonSTT operator. Without having an unexpired IAM access token, STT service on public cloud will not allow the speech to text transcription to happen.
This operator has 2 operation modes:
- If parameter accessToken is nonempty, the operator emits one output tuple with the access token and the operator
thread ends.
- If parameter accessToken is empty, the operator connects to the IAM authorization service specified by parameter
iamTokenURL and requests an access token by using the provided
apiKey. The received access token is submitted to the output port. This operator refreshes the access token automatically after the expiration time by using the received refresh token and submits the refreshed access token to the output port. If IAM authentication server responses with a non successful result, the operator re-tries the operation after
failureRetryDelay.
The operator gets the configuration information from operator parameters. These values may be overwritten from Streams Application Configuration properties if an Application Configuration with name defined by parameter appConfigName and the appropriate property exists.
Metrics: The following metrics are available if the operator generates and refreshes the access token from IAM authorization service (parameter accessToken is empty).
nSuccessfulInitialRequests: The number of successful requests with grant_type=urn:ibm:params:oauth:grant-type:apikey. The authorization was granted in response to the request
nSuccessfulRefreshRequests: "The number of successful requests with grant_type=refresh_token. The authorization was granted in response to the request.
nRequestsFailed: The cumulative number of requests which return an error status or with invalid response body.
nConnectionAttemptsFailed: The cumulative number of failed connection attempts.
nConnectionAttemptsCurrent: The number of current consecutive connection attempts until the connection succeeds. If an connection attempt succeeds, this metric is reset to 0.
Parameters
- appConfigName: The name of the application configuration to look for connection parameters. If this parameter is nonempty, the properties from this application configuration overwrite the operator parameters. An empty string disables the lookup in the Application Configuration. This may be used if all non default parameters are supplied in the operator invocation. Type: rstring; Default: sttConnection
- accessToken: If parameter accessToken is nonempty, the operator emits one output tuple with the access token and the operator thread ends. If parameter accessToken is empty, the operator connects to the IAM authorization service specified by parameter iamTokenURL and requests an access token by using the provided apiKey. If the application configuration with name appConfigName and property accessToken exists, this parameter is overwritten. Type: rstring; Default: ""
- apiKey: The api key required for the generation of the access token. This parameter is evaluated when the operator logic starts to generate a initial or a refresh access token. Thus the parameter may be changed during operation of the streams application. If the value is the empty string, no access token is requested from IAM cloud service. When the value has changed, the operator requests an initial access token when the current token becomes invalid. If the application configuration with name appConfigName and property apiKey exists, this parameter is overwritten. Type: rstring; Default: ""
- iamTokenURL: The service url of the IAM Token authorization service to fetch and refresh the IAM access token. If the parameter is the empty string, the operator thread ends immediately. If the application configuration with name appConfigName and property iamTokenURL exists, this parameter is overwritten. Type rstring; Default: the empty string
- defaultExpiresIn: The default value for the access token expiration time in seconds. This value is used, when no expires_in value is returned from the authorization service. If the application configuration with name appConfigName and property defaultExpiresIn exists, this parameter is overwritten. Type: int64; Default: 3600
- guardTime: The guard time in seconds. A refresh token is requested 'guard time' seconds before the expiration was determined. If the application configuration with name appConfigName and property guardTime exists, this parameter is overwritten. Type: int64; Default: 300
- maxRetryDelay: The maximum wait time in seconds before a connection re-try is made. The connection re-try delay increases exponentially starting from 2 seconds but not exceeding 'maxRetryDelay'. This value is used in case of unsuccessful connection attempts due to (temporary) network issues. If the application configuration with name appConfigName and property maxRetryDelay exists, this parameter is overwritten. Type: float64; Default: 60.0
- failureRetryDelay: The maximum wait time in seconds before a new authorization attempt is made after a non successful server response. This value is used in case of unsuccessful authorization attempts due to a final failure response from the authorization server or due to an empty apiKey. If the application configuration with name appConfigName and property failureRetryDelay exists, this parameter is overwritten. Type: float64; Default 120.0
- initDelay: The initial delay before the operation starts in seconds. Type: float64; Default 0.0
- expiresInTestValue: This value is used mainly for tests. If this value is different from 0.0, it overwrites the received expires_in value. Type float64; Default 0.0
Output Ports
- IamAccessTokenStream: The output stream with the generated access token and other information received from IAM authentication service. The stream must be of type com.ibm.streamsx.sttgateway.watson::IAMAccessToken. The output generates a tuple once a initial or refreshed access token is available.
Types
IAMAccessToken
This type represents the data format for the result returned by the IAMAccessTokenGenerator
IAMAccessToken = rstring access_token, rstring refresh_token, rstring scope, int64 expiration, rstring token_type, int64 expires_in;