Tutorial: Create a file

This tutorial shows you how to create a file in the cloud via the File Management Service.

Prerequisites

To complete this tutorial, the following prerequisites must be in place:

1. You must have a service access key that allows access to the File Management Service. As you may recall from the previous tutorial, each access key has a scope that describes the extent of access to SBS services. For this example, generate a key as described in Generate a service access key, and make sure to set the key’s scope to file-management-api:query:* file-management-api:mutation:*, which would provide access to all queries and mutations of the File Management Service.

2. This tutorial uses cURL (https://curl.se) to initiate HTTP requests. Therefore, cURL must be installed and available in your terminal. You can easily check if that is the case by running the following command in your terminal:

   Copy

   curl --version
   

If you prefer not to use cURL, you could also use a REST client such as Postman and Fiddler and achieve the same result.

Step 1: Populate the HTTP header

To access the File Management Service, you must populate the x-api-key HTTP header of the request with the service access key. This tutorial assumes you are using a GraphQL console to call the service, in which case the steps are as follows:

1. Go to https://file-management-api.socrate.io/graphql.
2. Click HTTP Headers in the lower area of the page.
3. Enter you service access key as value of the x-api-key header:

{"x-api-key": "YOUR_SERVICE_ACCESS_KEY"}

Step 2: Create a file

To create a new file in the cloud, run the following mutation:

mutation create_file($input:CreateFileInput) {
  createFile(input: $input) {
		id
  }
}

{
  "input": {
    "name": "file1.txt"
  }
}

Once you run the mutation, the result will contain the unique ID of the created file. Take notice of this ID; you will need it in subsequent steps.

Step 3: Generate the upload URL

So far, the file created in the cloud has no content. To create some file content, you must first generate a temporary URL at which you can upload the content. Run the following GraphQL query to obtain the upload URL:

query($filter:FilesFilter, $sec:Int) {
  files(filter:$filter){
    items {
      id
      name
      status
      uploadUrl(expiresIn: $sec)
    }
  }
}

In variables, make sure to replace the file ID with the one you obtained previously. Also, note that the URL expiration period is set to 5 minutes (300 seconds); feel free to change this value as required.

{
  "filter": {
    "id": "YOUR_FILE_ID"
  },
  "sec": 300
}

The result is similar to the one below:

{
  "data": {
    "files": {
      "items": [
        {
          "id": "cf0c9840-ce2e-11ed-b8cc-afe40ad143c4",
          "name": "file1.txt",
          "status": "uploading",
          "uploadUrl": "SOME_GENERATED_UPLOAD_URL"
        }
      ]
    }
  }
}

In the code listing above, notice that the file status is “uploading”. The reason is that the file has no content yet, and it awaits file content to be uploaded. The uploadURL field of the response contains the generated URL that you will need in the next step.

Step 4: Upload the file content

To simulate the upload of the actual file content, we will be using cURL in this example. If you are using a tool like Postman or Fiddler, or perhaps program code written in a language of your choice, the upload operation consists of initiating a PUT request that takes content from a local .txt file and sends it to the upload URL obtained previously.

1. Create a test.txt file on your local computer and edit it so that it contains some dummy text that you want to use as file content.

2. Do one of the following:

• If you have a bash terminal, run:
  Copy

  curl --location --request PUT 'YOUR_UPLOAD_URL' --header 'Content-Type: text/plain' --data '@/path/to/your/test.txt'
  

• If you have a Windows terminal, run:
  Copy

  curl --location --request PUT "YOUR_UPLOAD_URL" --header "Content-Type: text/plain" --data "@C:\test.txt"
  

View the updated file content

To view or download the file, you must create a temporary download URL, as illustrated in the code listing below.

query($filter:FilesFilter, $sec:Int) {
  files(filter:$filter){
    items {
      id
      name
      status
      downloadUrl(expiresIn: $sec)
    }
  }
}

Note that in the code listing below the URL is set to expire in 5 minutes (300 seconds); you can change this value as required.

{
  "filter": {
    "id": "YOUR_FILE_ID"
  },
  "sec": 300
}

The result will include the generated download URL, for example:

{
  "data": {
    "files": {
      "items": [
        {
          "id": "cf0c9840-ce2e-11ed-b8cc-afe40ad143c4",
          "name": "file1.txt",
          "status": "done",
          "downloadUrl": "YOUR_DOWNLOAD_URL"
        }
      ]
    }
  }
}

You can now use cURL (or another REST client) to check that the new file content is available at the download URL.

For bash terminals, run:

curl --location 'YOUR_DOWNLOAD_URL'

For Windows terminals, run:

curl --location "YOUR_DOWNLOAD_URL"