첨부파일 업로드(Upload Attachment) (V2)

액션에서 사용할 임시 첨부파일을 업로드합니다. 파일 바이트를 본문으로 보내고 Content-Type: application/octet-stream을 사용합니다. 업로드한 뒤 한 시간 안에 액션으로 객체에 연결하지 않은 첨부파일은 제거됩니다. 이전에는 연결되어 있었지만 현재 어떤 객체에도 연결되지 않은 파일은 격주(biweekly) 정리 대상입니다.

반환된 첨부파일 RID를 액션의 첨부파일 매개변수에 전달하여 객체에 연결합니다. 파일 이름은 필수 쿼리 매개변수 filename으로 제공하며 URL에 맞게 인코딩합니다. 크기와 누적 연결 개수의 한도는 첨부파일 수명을 따릅니다.

HTTP 요청

POST /api/v2/ontologies/attachments/upload

작업 식별자는 v2.uploadAttachmentV2입니다. OAuth2로 호출하는 타사 애플리케이션에는 api:ontologies-write 권한 범위가 필요합니다. 각 요청에 Authorization: Bearer <접근 토큰>을 전달합니다.

경로 매개변수

지정할 경로 매개변수가 없습니다.

쿼리 매개변수

요청 본문

필수 본문은 파일의 원본 바이트입니다. Content-Type은 application/octet-stream입니다.

응답

응답 형식은 AttachmentV2입니다.

전체 필드는 첨부파일 메타데이터를 따릅니다.

첨부파일 메타데이터의 응답 예시입니다.

{
  "rid": "ri.attachments.main.attachment.bb32154e-e043-4b00-9461-93136ca96b6f",
  "filename": "My Image.jpeg",
  "sizeBytes": 393469,
  "mediaType": "image/jpeg"
}

개별 오류

오류 응답 처리는 공통 API 오류 계약을 따릅니다.

요청 예제

FOUNDRY_HOST에는 https://를 제외한 Foundry 호스트를, FOUNDRY_TOKEN에는 유효한 토큰을 제공합니다.

파일 이름은 실제 업로드할 파일에 맞춰 바꿉니다.

MEDIA_UPLOAD_FILE은 업로드할 로컬 파일의 경로입니다. 파일 내용을 바이너리로 전송합니다. JavaScript 예제는 스트림 요청 본문을 지원하는 Node.js에서 ES 모듈(.mjs)로 실행합니다.

cURL

curl --fail -X POST \
	-H "Content-type: application/octet-stream" \
	-H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
	"https://${FOUNDRY_HOST}/api/v2/ontologies/attachments/upload?filename=My+Image.jpeg" \
	--data-binary "@${MEDIA_UPLOAD_FILE}"

Python

Requests 라이브러리가 설치된 환경에서 사용합니다.

import os
import requests

HOSTNAME = os.environ["FOUNDRY_HOST"]
TOKEN = os.environ["FOUNDRY_TOKEN"]
headers = {
    "content-type": "application/octet-stream",
    "authorization": "Bearer {}".format(TOKEN)
}

with open(os.environ["MEDIA_UPLOAD_FILE"], "rb") as media_file:
    with requests.post('https://{}/api/v2/ontologies/attachments/upload?filename=My+Image.jpeg'.format(HOSTNAME), headers=headers, data=media_file) as response:
        response.raise_for_status()
        print(response.json())

Java

Apache HttpClient 4.5 API를 사용하는 UploadAttachmentV2Example.java 예제입니다.

import java.io.File;
import java.io.IOException;
import org.apache.http.entity.FileEntity;
import org.apache.http.util.EntityUtils;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;

public class UploadAttachmentV2Example {
    public static void main(String[] args) throws Exception {
        String HOSTNAME = System.getenv("FOUNDRY_HOST");
        String TOKEN = System.getenv("FOUNDRY_TOKEN");

        try (CloseableHttpClient httpClient = HttpClientBuilder.create().build()) {
            HttpPost request = new HttpPost("https://" + HOSTNAME + "/api/v2/ontologies/attachments/upload?filename=My+Image.jpeg");
            request.addHeader("content-type", "application/octet-stream");
            request.addHeader("authorization", String.format("Bearer %s", TOKEN));
            request.setEntity(new FileEntity(new File(System.getenv("MEDIA_UPLOAD_FILE"))));
            try (CloseableHttpResponse response = httpClient.execute(request)) {
                int status = response.getStatusLine().getStatusCode();
                if (status < 200 || status >= 300) throw new IOException("HTTP " + status);
                System.out.println(EntityUtils.toString(response.getEntity(), "UTF-8"));
            }
        }
    }
}

JavaScript

fetch를 제공하는 Node.js 환경에서 사용합니다. import가 있는 예제는 ES 모듈(.mjs)로 실행합니다. 서비스 사용자 토큰을 브라우저로 전달하지 않습니다.

import { createReadStream } from "node:fs";

const HOSTNAME = process.env.FOUNDRY_HOST;
const TOKEN = process.env.FOUNDRY_TOKEN;

const mediaFile = createReadStream(process.env.MEDIA_UPLOAD_FILE);
try {
    const response = await fetch(`https://${HOSTNAME}/api/v2/ontologies/attachments/upload?filename=My+Image.jpeg`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/octet-stream',
        'Authorization': `Bearer ${TOKEN}`,
    },
    body: mediaFile,
    duplex: 'half'
});
    if (!response.ok) {
        await response.body?.cancel();
        throw new Error(`HTTP ${response.status}`);
    }
    console.log(await response.json());
} finally {
    mediaFile.destroy();
}

PowerShell

스크립트 오류가 발생하면 중단하도록 ErrorActionPreference를 설정합니다.

$ErrorActionPreference = 'Stop'
$TOKEN = $env:FOUNDRY_TOKEN
$HOSTNAME = $env:FOUNDRY_HOST

$headers = @{
    "authorization" = "Bearer $TOKEN"
}

$response = Invoke-WebRequest -Uri "https://$HOSTNAME/api/v2/ontologies/attachments/upload?filename=My+Image.jpeg" `
	-Method Post `
	-Headers $headers `
	-ContentType application/octet-stream `
	-InFile $env:MEDIA_UPLOAD_FILE

$response.content