Connecting
To use the Squonk2 Data Manager or Account Server API you will need a user access token.
If you do not have a token the method Auth.get_access_token()
will
return one from an appropriate keycloak instance and user credentials.
Every API method will need an access token.
In this example we use the Python argparse
module to extract sensitive keycloak
material form the command line and the os.environ
module to get a username
and password from a pair of environment variables.
import argparse
import os
from squonk2.auth import Auth
# Username and password are taken from environment variables...
keycloak_user: str = os.environ['DMAPI_USERNAME']
keycloak_user_password: str = os.environ['DMAPI_USERNAME_PASSWORD']
# Less sensitive information is extracted from the command-line...
parser = argparse.ArgumentParser(description='Delete All DM Project Instances')
parser.add_argument('--keycloak-hostname', '-k',
help='The API URL, i.e. "example.com"',
required=True)
parser.add_argument('--keycloak-realm', '-r',
help='The Keycloak realm, i.e. "blob"',
required=True)
parser.add_argument('--keycloak-client-id', '-i',
help='The Keycloak client ID, i.e. "data-manager-api-dev"',
required=True)
args = parser.parse_args()
# Now get an API token.
# It should be valid for the remainder of the utility...
token: str = Auth.get_access_token(
keycloak_url='https://' + args.keycloak_hostname + '/auth',
keycloak_realm=args.keycloak_realm,
keycloak_client_id=args.keycloak_client_id,
username=keycloak_user,
password=keycloak_user_password,
)
Note
That this assumes you hav a Keycloak account with a username and password.
If you have only used a federated login (e.g. CAS, GitHub etc.) then you
may not have a password. To create one go to your Keycloak account
(e.g. https://<server-name>/auth/realms/<realm-name>/account
),
login with whatever mechanism you use and then give yourself a password
in the Password section.
API response data
Depending on which API method is used, when successful,
the Data Manager response payload (its JSON content) is returned
as a Python dictionary in the DmApiRv.msg
property.
For example, when successful the DmApi.start_job_instance()
will return
the assigned Task and Instance identities.
spec = {'collection': 'im-test', 'job': 'nop', 'version': '1.0.0'}
rv: DmApiRv = v.start_job_instance(
token,
project_id=project_id,
name='My Job',
specification=spec
)
assert rv.success
rv.msg
{'task_id': 'task-...', 'instance_id': 'instance-...'}
Consult the DM API for up-to-date details of the payloads you can expect.
Errors
If the result of an API call fails (DmApiRv.success
is False
)
an error message can typically be found in the DmApiRv.msg
, a dictionary,
using the key error
.
rv.msg
{'error': 'No API URL defined'}