Quick Start

This page gives an introduction on how to get started with the ambra-sdk library. First, make sure that ambra-sdk is installed and up-to-date. Let’s get started with some simple examples.

Init API

Begin by importing the ambra-sdk module:

from ambra_sdk.api import Api

To use ambra-sdk one needs to know the url of AmbraHealth API and SID.

api = Api.with_sid(url, sid)  # Init API with sid

Note

Usually, URL has a form:

url = https://ambrahealth_host/api/v3

Another option is to use user credentials (username and password) and ambra-sdk takes care of using the sid for the session:

api = Api.with_creds(url, username, password)

client_name to ambra-sdk constructors can be used. This value will be added to the SDK request headers. Thus, AmbraHealth will be able to understand and log who exactly is making requests to help troubleshoot issues.

api = Api.with_creds(url, username, password, client_name)

Service API

All ambra-sdk service API methods are described in the AmbraHealth Service API document and all of them are divided by namespaces. In ambra-sdk we have the same separation of methods by namespaces.

All methods in AmbraHealth service API can be divided on two groups:

• Methods with one result

• Methods with multiple results

In order to deal with the first group, use get() method for getting results from a prepared request. Alternatively, multiple results can be retrieved by using first() or all() methods to get the first row of results or getting an iterator over all results.

For example, let’s request your user information. This is user method in session namespace, so we should use an api.Session.user method of ambra-sdk.

This is a simple method with only one result, so for fetching data from the service, use the get() method:

from ambra_sdk.api import Api
api = Api.with_creds(url, username, password)
user_info = api.Session.user().get()
print(user_info.email)

Let’s look at another example where we are using methods that return multiple results. One of these methods is the account list method.

Let’s get a first object in results:

account = api.Account.list().first()

all() method returns an iterator over all elements:

# Get all accounts
accounts = api.Account.list().all()

One can use slices for skipping and taking some number of results:

# Get 7 results after skipping the first 5 rows.
accounts = api.Account.list().all()[5:12]

Now, iterate over all accounts:

for account in accounts:
    account_name = account.name

Note

ambra-sdk all() method returns a lazy iterator. It means that we request new data from AmbraHealth API only when we actually need it.

Storage API

All ambra-sdk storage API methods are described in the AmbraHealth Storage API document .

As in the server documentation in ambra-sdk, all api requests to storage are divided into Study and Image namespaces.

For accessing storage api methods, use the ambra-sdk api.Storage namespace.

For example, let’s try to upload a dicom file to your user namespace.

Let’s get your user namespace_id and engine_fqdn using ambra-sdk service api User.get and Namespaces.engine_fqdn methods:

user = api.User.get().get()
namespace_id = user.namespace_id
fqdn = api.Namespace.engine_fqdn(namespace_id=namespace_id).get()
engine_fqdn = fqdn.engine_fqdn

Then, upload dicom file to the storage:

dicom_path = 'PATH_TO_DICOM'
with open(dicom_path, 'rb') as dicom_file:
    uploaded_image = api.Storage.Image.upload(
        engine_fqdn=fqdn.engine_fqdn,
        namespace=namespace_id,
        opened_file=dicom_file,
    )

Note

Unlike service API methods, storage methods do not use get(), first() or all().

Addon methods

All service and storage api methods are described in the AmbraHealth specification documents. In ambra-sdk, all methods outside of this specifications are placed in the Addon namespace.

For example, one common task is to upload a new study in AmbraHealth, upload dicom files to storage, and wait for a new study object in service. Use api.Addon.Study.upload_and_get method:

from pathlib import Path
study_dir = Path('/path_to_study_dir')

new_study = api.Addon.Study.upload_and_get(
    study_dir=study_dir,
    namespace_id=user_info.namespace_id
)