POST -Add Label

Introduces the invocation method of the Labeling interface.

POST Request Description

A complete POST request should include the following four parameter contents:
  • url: The request address.
  • headers: The HTTP headers of the request.
  • data: The metadata information sent, example format:
    metadata = {
        "app": "appA",
        "queryID": str(uuid.uuid4()),
        "update": True,
        "sendBack": {"type": "response"},
        "labels": {
            "employID": "12340017",
        }
    }
  • files: Local files to be operated on.
Note: For the complete code example, refer to the Python Request Example below.

Request URL

https://<ucwi_endpoint>:5443/skg/v1/dlp/label/custom/<request_mode>
Parameter Name Parameter Location Required Description
<request_mode> url Yes
  • sync - Synchronous mode
  • async - Asynchronous mode

Request Header

Parameter Name Parameter Location Required Description
authorization header Yes Authentication information in the request. For more details, refer to the chapter Authentication.
x-skg-timestamp header Yes The current timestamp. For more details, refer to the chapter Authentication.

Metadata in the Request Body

Parameter Name Type Applicable Status Description
labels Dict (Required) Synchronous and asynchronous Custom label content to be added
app String (Required) Synchronous and asynchronous Webservice application ID
update Boolean (Optional) Synchronous and asynchronous Whether to update existing labels, default is False
sendBack Dict (Required) Synchronous and asynchronous Handling method for returning files after labeling. Supports local return, HTTP upload, and cloud storage such as Amazon S3 and Swift.
  • response: Return the labeled content to the current path. The following is a code example:
    {
        "queryID": "1075893f-b0ed-4a76-a07d-df3d2fc0de46",
        ......
        "sendBack": {
            "type": "response", # Return the labeled content to the current path
        }
    }
  • httpUpload: Send the labeled content to the specified URL. The following is a code example:
    {
        "queryID": "1075893f-b0ed-4a76-a07d-df3d2fc0de46",
        ......
        "sendBack": {
            "type": "httpUpload",
            "url": "http://172.11.11.6/callback ", 
             # Send the labeled content to this URL
        }
    }
  • s3: Upload the labeled content to the specified location in S3 object storage. The following is a code example:
    {
        "queryID": "1075893f-b0ed-4a76-a07d-df3d2fc0de46",
        ......
        "sendBack": {
            "type": "s3",
            "s3Bucket": "test",
            "s3Region": "",  
             # Upload the file to this location.
             # This value is the region name when using S3.
             # If running on EC2 and using AWS IAM role, the following three items can be omitted
            "accessKey": "aws_accessKey",
            "secretKey": "aws_secretKey",
            "endpointUrl": "",
        }
    }
    swift: Upload the labeled content to the specified location in Swift object storage. The following is a code example:
    {
        "queryID": "1075893f-b0ed-4a76-a07d-df3d2fc0de46",
        ......
        "sendBack": {
            "type": "swift",
            "X-Auth-Token": "AUTH_tkbdac2a3474ee4d6396133c99cfd962c8",  
             # Authentication token when using Swift.
             # If the provided X-Auth-Token is valid, the following three items can be omitted.
            "authUrl": "http://172.22.117.120:8080/auth/v1.0 ",
            "X-Auth-User": "test",
            "X-Auth-Key": "test",
            "objectUrl": "http://172.22.117.120:8080/auth/v1.0/AUTH_test/container1/1.txt ",  
             # Upload the labeled file to this object URL location in Swift object storage.
             # Choose one between objectUrl and ContainerUrl.
            "containerUrl": "", 
             # Upload the labeled file to this container URL location in Swift object storage.
             # Choose one between objectUrl and ContainerUrl.
        }
    }
queryID String (Required) Synchronous and asynchronous sync/async (synchronous or asynchronous mode)
uploadtype String (Required) Asynchronous Only for asynchronous mode. Supports cloud storage such as AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, and Swift.
  • swift
  • oss
  • cos
  • s3
callback_url String (Required) Asynchronous Must be filled for asynchronous mode with the callback function URL
objectInfo Dict (Optional) Asynchronous Only for asynchronous mode when using object storage. Asynchronous mode supports reviewing objects stored in Amazon S3, Swift, Alibaba Cloud OSS, Tencent Cloud COS, and other cloud services. For specific parameter settings, refer to the chapter: objectinfo Parameters for Reviewing Cloud Service Stored Content in Asynchronous Mode

Synchronous Request Parameter Example

{   
    "app": "875a2442-2fe6-49a5-abf7-00fbd727e99e",
    "queryID": "8a0aa812-0f80-4d25-8e3f-60583bac8b96",
    "update": True,
    "labels": {
        "test_key": "tt_value",
        "id": "8888"
    },
    "sendBack": {
        "type": "response"
    }
}

Asynchronous Request Parameter Example

{
    "labels": {
        "test_key": "tt_value",
        "id": "8888"
    },
    "app": "875a2442-2fe6-49a5-abf7-00fbd727e99e",
    "update": True,
    "queryID": "8a0aa812-0f80-4d25-8e3f-60583bac8b96",
    "callback_url": "http://172.11.9.1:8000/callback",
    "sendBack": {
        "type": "s3",
        "s3Bucket": "leo",
        "s3Region": "",  # Region name when using S3. If running on EC2 and using AWS IAM role, the following three items can be omitted
        "accessKey": "admin",
        "secretKey": "admin",
        "endpointUrl": "http://172.20.162.160:9000",
    },
    "uploadtype": "file"
}

Python Request Example - Labeling

The following example demonstrates using Python code to call the interface to label a local file.

Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import os
import uuid
import time
from requests_toolbelt.multipart import decoder

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

api = "/skg/v1/dlp/label/custom/sync"
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path="CustomLabelTest.docx.RET.RET"

metadata = {
    "app": "appA",
    "queryID": str(uuid.uuid4()),
    "update": True,
    "sendBack": {"type": "response"},
    "labels": {
        "employID": "12340017",
        "Student-name": "peter",
        "BBB-XXX": "2222222",
        "EEE-XXX": "555555",
    }
}

headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path, 'rb')
files = {
    "request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    if response.headers['Content-Type'] == 'application/json':
        info = response.json()
        print(info)
    elif response.headers['Content-Type'].startswith('multipart/form-data'):
        multipart_data = decoder.MultipartDecoder.from_response(response)
        for part in multipart_data.parts:
            content = part.content
            content_type = part.headers[b'content-type']
            content_disposition = part.headers[b'content-disposition']

            if content_type == b"application/json":
                info = json.loads(content)
                print("multipart info:{}".format(info))
            elif content_type == b"application/octet-stream":
                cd_info = [x.strip()
                           for x in content_disposition.decode('utf-8').split(';')]
                print("multipart xxx {}".format(cd_info))
                for item in cd_info[1:]:
                    index = item.find('=')
                    key, value = item[:index], item[index + 1:]
                    if key == 'filename':
                        filename = value.strip('"') + ".RET"
                        with open(filename, 'wb') as f:
                            f.write(content)

Error code

If calling the API has an error, the following error codes are returned:
Error Code Description
400 Invalid parameter
404 Unknown Error
500 Invalid parameter