Merge pull request #9 from benchling/ddeutsch-blob-upload

docs: Add example for blob uploading BNCH-27939

Author: daniel-deutsch-benchling

README.md

@@ -5,3 +5,4 @@ This repository contains examples of how to use Benchling's API.
 - `sync_into_benchling/` shows how to import and register entities
 - `sync_out_of_benchling/` shows how to export all registered entities modified after a certain timestamp
 - `upload_results/` shows how to upload data from a plate reader as structured results
+- `blob_upload/` shows how to upload a blob attachment

blob_upload/Pipfile

@@ -0,0 +1,17 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+certifi = "==2021.5.30"
+chardet = "==4.0.0"
+idna = "==2.10"
+requests = "==2.25.1"
+urllib3 = "==1.26.6"
+click = "*"
+
+[dev-packages]
+
+[requires]
+python_version = "3.9"

blob_upload/Pipfile.lock

@@ -0,0 +1,18 @@
+# **Upload Blobs To Benchling**
+
+Example code for uploading blobs to Benchling, part of the [Uploading Instrument Results](https://docs.benchling.com/docs/example-creating-results) guide available on Benchling Developer Platform Documentation Page.   
+
+# How to run the script
+
+- First, ask Benchling support to enable API access on your account, and create API credentials. Instructions: https://help.benchling.com/articles/2353570-access-the-benchling-api-enterprise
+- Install Python 3 and [Pipenv](https://docs.pipenv.org/en/latest/)
+- Install dependencies using `pipenv install`
+- Run `pipenv shell` to work in a virtualenv that includes the dependencies.
+- Run the script. For example:
+
+```
+python blob_upload.py \
+  --domain example.benchling.com \
+  --api-key $YOUR_API_KEY \
+  --filepath path/to/chromatogram_file
+```

blob_upload/README.md

@@ -0,0 +1,107 @@
+import json
+import os
+
+import click
+import requests
+import time
+
+from file_helpers import calculate_md5, encode_base64
+
+CHUNK_SIZE_BYTES = int(10e6)
+
+class BadRequestException(Exception):
+    def __init__(self, message, rv):
+        super(BadRequestException, self).__init__(message)
+        self.rv = rv
+
+
+def api_post(domain, api_key, path, body):
+    url = "https://{}/api/v2/{}".format(domain, path)
+    rv = requests.post(url, json=body, auth=(api_key, ""))
+    if rv.status_code >= 400:
+        raise BadRequestException(
+            "Server returned status {}. Response:\n{}".format(
+                rv.status_code, json.dumps(rv.json())
+            ),
+            rv,
+        )
+    return rv.json()
+
+
+@click.command()
+@click.option(
+    "--domain",
+    help="Domain name of your Benchling instance, e.g. example.benchling.com",
+    required=True,
+)
+@click.option("--api-key", help="Your API key", required=True)
+@click.option("--filepath", help="Filepath of blob to upload", required=True)
+@click.option("--destination-filename", help="Name of file (omit to keep same name as source)", required=False)
+def main(
+        domain,
+        api_key,
+        filepath,
+        destination_filename,
+):
+    name = destination_filename
+    if name is None:
+        name = os.path.basename(filepath)
+    file_size = os.path.getsize(filepath)
+    with open(filepath, "rb") as file:
+        if file_size <= CHUNK_SIZE_BYTES:
+            upload_single_part_blob(api_key, domain, file, name)
+        else:
+            upload_multi_part_blob(api_key, domain, file, name)
+
+
+def upload_single_part_blob(api_key, domain, file, name):
+    file_contents = file.read()
+    encoded64 = encode_base64(file_contents)
+    md5 = calculate_md5(file_contents)
+    res = api_post(domain, api_key, "blobs", {
+        "data64": encoded64,
+        "md5": md5,
+        "mimeType": "application/octet-stream",
+        "name": name,
+        "type": "RAW_FILE",
+    })
+    assert(res["uploadStatus"] == "COMPLETE")
+    print("Finished uploading {} with blob ID {}".format(
+        res["name"], res["id"]
+    ))
+
+
+def upload_multi_part_blob(api_key, domain, file, name):
+    chunk_producer = lambda chunk_size: file.read(chunk_size)
+    start_blob = api_post(domain, api_key, "blobs:start-multipart-upload", {
+        "mimeType": "application/octet-stream",
+        "name": name,
+        "type": "RAW_FILE",
+    })
+    part_number = 0
+    blob_parts = []
+    try:
+        while True:
+            cursor = chunk_producer(CHUNK_SIZE_BYTES)
+            if not cursor:
+                break
+            part_number += 1
+            encoded64 = encode_base64(cursor)
+            md5 = calculate_md5(cursor)
+            created_part = api_post(domain, api_key, "blobs/{}/parts".format(start_blob["id"]), {
+                "data64": encoded64,
+                "md5": md5,
+                "partNumber": part_number,
+            })
+            blob_parts.append(created_part)
+        api_post(domain, api_key, "blobs/{}:complete-upload".format(start_blob["id"]), {
+            "parts": blob_parts
+        })
+        print("Completed uploading {} parts for blob {}".format(part_number, start_blob["id"]))
+    except Exception as e:
+        print("Error while uploading part {} for blob {}".format(part_number, start_blob["id"]))
+        api_post(domain, api_key, "blobs/{}:abort-upload".format(start_blob["id"]), {})
+        raise e
+
+if __name__ == "__main__":
+    main()

blob_upload/blob_upload.py

@@ -0,0 +1,11 @@
+import base64
+import hashlib
+
+
+def encode_base64(input: bytes, charset: str = "utf-8") -> str:
+    file_bytes = base64.encodebytes(input)
+    return str(file_bytes, charset)
+
+
+def calculate_md5(input: bytes) -> str:
+    return hashlib.md5(input).hexdigest()

blob_upload/file_helpers.py

@@ -0,0 +1,5 @@
+certifi==2021.5.30
+chardet==4.0.0
+idna==2.10
+requests==2.25.1
+urllib3==1.26.6