Using APIs (TMS)

컨텐츠는 영어 텍스트를 Phrase Language AI를 이용해 기계 번역한 것입니다.

이것은 샘플 API 호출과 함께 API만을 사용해서 간단한 작업을 완료하는 방법에 대한 안내가 포함된 간단한 API 시나리오야. API를 통해 설정할 수 있는 옵션은 광범위해. 모든 사용 가능한 옵션에 대해 더 알아보려면 REST API 문서의 해당 섹션을 참고해.

이 시나리오는 Postman API 플랫폼을 사용해 만들어졌어.

이 예제에서 표준 요청 URL은 https://cloud.memsource.com로 시작해. 미국 데이터 센터의 조직에서 API를 사용할 경우 요청 URL은 https://us.cloud.memsource.com로 시작해야 해.

시나리오

인증

사용자가 인증돼(API에서 로그인과 같은 과정이야).
생성

간단한 프로젝트 생성, 작업 업로드, 그리고 이메일 알림과 함께 번역자 할당이 이루어져.
번역

API 시나리오 외부에서 번역 작업이 진행돼(편집기 모두에서).
API 기능

할당이 완료되면(번역자가 완료로 표시하면), 프로젝트의 상태가 완료로 변경되고, 완료된 문서를 프로젝트에서 다운로드해.

방법론

각 개별 REST API 호출에는 적절한 메서드가 나열돼. 잘못된 메서드(예: 프로젝트 생성 호출에서 POST 대신 GET 사용)를 사용하면 API 호출이 실패해.

1단계: 인증

두 가지 인증 방법이 있어:

인증 API 호출:

24시간 유효한 인증 토큰을 생성해. 토큰은 모든 이후 API에 삽입해야 해. 토큰은 사용자를 검증하고 프로필 내에서 다른 모든 기능을 수행할 수 있게 해.
oAuth 2.0

애플리케이션의 유효성을 검사할 수 있어. 검증된 애플리케이션은 지속적으로 통신하고 추가 인증이 필요 없어.

이 시나리오에서는 인증 API 호출이 사용돼. 생성된 토큰은 모든 후속 API 호출에 필요하고 예제 매개변수에 나열되지 않아.

인증을 위해 필요한 매개변수와 함께 Login API를 사용해. 이 경우, username와 password가 필요해.

메서드

POST
요청 URL

https://cloud.memsource.com/web/api2/v3/auth/login

요청 본문:

{ "userName":"username", "password":"password"}

응답

인증 토큰.

여러 TMS 조직의 멤버는 여러 계정에서 동일한 사용자 이름과 비밀번호를 사용해. 이 경우, userUid는 사용자가 로그인하려는 조직을 지정하기 위해 요청 본문에 추가돼야 해. 지정하지 않으면 사용자는 주어진 사용자 이름과 비밀번호와 연결된 기본 계정에 로그인돼.

2단계: 프로젝트 생성, 가져오기 및 할당

프로젝트 생성

프로젝트 API 호출을 사용해서 필수 매개변수 name, sourceLang, 그리고 targetLangs로 프로젝트를 생성해.

메서드

POST
요청 URL

https://cloud.memsource.com/web/api2/v3/projects

요청 본문

{ "name":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}

응답

프로젝트 UID (예: KmtNyVlz1skQd2aMVEipp7)

마지막 호출에서 받은 프로젝트 UID로 프로젝트 템플릿 생성 API를 사용해 프로젝트 템플릿을 만들 수 있어.

메서드

POST
요청 URL

https://cloud.memsource.com/web/api2/v1/projectTemplates

요청 본문

{
  "project": {
    "uid": "string"
  },
  "name": "string",
  "importSettings": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

응답

프로젝트 템플릿 UID (예: AmtNyVlz1skQd2aMVEipp8)

프로젝트를 생성하는 가장 효율적인 방법은 프로젝트 템플릿을 사용하는 거야. 마지막 호출에서 가져온 프로젝트 템플릿 UID로 템플릿에서 프로젝트 생성을 사용해 프로젝트 템플릿의 설정을 기반으로 새 프로젝트를 생성해.

표현식 {projectUid}는 요청 URL에서 얻은 프로젝트 UID가 삽입되는 자리 표시자로 사용돼.

메서드

POST
요청 URL

https://cloud.memsource.com/web/api2/v2/projects/applyTemplate/oNQiljwTGHpd2l1nnQRiu4

요청 본문

{
  "name": "string",
  "sourceLang": "string",
  "targetLangs": [
    "string"
  ],
  "workflowSteps": [
    {
      "id": "ID"
    }
  ],
  "dateDue": "2019-08-24T14:15:22Z",
  "note": "string",
  "client": {
    "id": "string"
  },
  "businessUnit": {
    "id": "string"
  },
  "domain": {
    "id": "string"
  },
  "subDomain": {
    "id": "string"
  },
  "costCenter": {
    "id": "string"
  }
}{
  "project": {
    "uid": "string"
  },
  "name": "string",
  "importSettings": {
    "uid": "string"
  },
  "useDynamicTitle": true,
  "dynamicTitle": "string"
}

응답

프로젝트 UID (예: BmtNyVlz1skQd2aMVEipp9)

작업 생성

마지막 호출에서 가져온 프로젝트 UID로 작업 생성을 사용해서 새로 생성된 프로젝트에 새 작업을 바로 추가할 수 있어.

표현식 {projectUid}는 요청 URL에서 얻은 프로젝트 UID가 삽입되는 자리 표시자로 사용돼. Create Job API 호출을 사용하면 요청의 Headers를 Phrase에서 요구하는 것과 일치하도록 변경해야 해(다른 호출에서는 Postman이 자동으로 적절한 헤더를 요청에 추가해).

모든 가져오기 매개변수는 사용자 지정 Memsource 헤더에 삽입되어야 해.

Content-Disposition 헤더에는 가져오기 요청을 올바르게 처리하기 위해 미리 정의된 형식으로 파일 이름이 포함되어야 해.

소스 파일을 가져오려면 본문으로 이동해 binary를 선택하면 Select File 옵션이 나타나.

Method

POST
Request URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
(Header) Content-Disposition

filename*=UTF-8''file.txt
(Header) Memsource

{"targetLangs":["de","fr"]}
(Header) Content-Type

application/octet-stream
응답

작업 UID(예: dOYgeXzAdAbj4xFjuEVZP2)

AsyncRequest UID

생성 작업 호출에서 AsyncRequest UID와 함께 Get asynchronous request를 사용해 작업이 성공적으로 생성되었고 기능이 있는지 확인해.

반환된 작업 UID는 프로젝트의 각 워크플로 단계에서 고유해. 따라서 작업이 워크플로가 있는 프로젝트에서 생성되면 응답은 각 워크플로 단계에 대해 고유한 작업 UID를 반환해.

재사용 가능한 가져오기 설정은 가져오기 설정 생성 호출로 설정할 수 있어. 생성 작업 호출에서 사용할 수 있는 가져오기 설정 UID가 응답으로 수신돼.

작업에 공급자를 할당하려면 (생성 작업 호출에서 직접 할당되지 않은 경우) 작업 편집 호출을 사용해.

호출에 삽입된 공급자의 ID는 두 가지 방법으로 얻을 수 있어:

Phrase 애플리케이션에서 ID를 검색하려면 다음 단계를 따라:
1. 설정 페이지에서 아래로 스크롤해 Administration 섹션으로 이동한 다음 사용자를 클릭하거나, 사이드바에서 사용자를 클릭해.
  
  사용자 페이지가 열려.
2. 사용자의 성을 클릭한 다음, 브라우저에서 URL의 마지막 부분을 복사해.
3. 이 부분을 해당 사용자 ID로 사용해.
사용해 사용자 목록 API 호출

이 API 호출은 특정 매개변수를 요구하지 않으며, 계정의 모든 사용자 목록을 반환해. 응답에는 사용자 이름과 ID가 모두 포함돼.

선택적 매개변수인 userName을 쿼리에 추가해서 특정 userName을 가진 사용자만 목록으로 볼 수 있어.

할당된 사용자에게 알림

작업 UID는 할당된 사용자에게 알림 호출에서 선택적 매개변수로 사용할 수 있고, 사용할 이메일 템플릿의 ID를 나타내는 매개변수와 함께 쓸 수 있어. 이는 이메일 템플릿 목록 호출을 사용해 얻을 수 있어.

요청 URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
응답

비어 있음 (상태 204: 컨텐츠 없음)

여기서 번역가는 문구 UI를 사용하는 것처럼 자신의 프로필에서 작업을 시작할 수 있어. 작업이 완료되면 담당 PM이 알림을 받고 시나리오의 다음 부분이 시작돼. 콜백은 웹 후크를 통해 가로챌 수 있어 시나리오의 다음 부분을 자동으로 시작할 수 있지만, 이 예제에서는 다루지 않아.

단계 3: 번역된 (완료) 파일 다운로드, 프로젝트를 완료로 설정

번역된 파일 다운로드

이 시나리오는 번역가가 작업을 완료(작업을 완료으로 표시)한다고 가정하지만, 완료된 파일은 언제든지 다운로드할 수 있고, 작업은 완료 상태일 필요 없어.

번역된 파일을 다운로드하려면 두 개의 API 호출이 필요해: 대상 파일 다운로드 (비동기) 및 비동기 요청에 따라 대상 파일 다운로드 호출.

첫 번째 단계는 대상 파일 다운로드 (비동기)를 projectUid 및 jobUid 매개변수와 함께 호출해. 여러 워크플로 단계가 있는 프로젝트에서 완료된 파일을 다운로드하는 경우, 다운로드하려는 완료된 파일의 특정 워크플로 단계에서 jobUid를 사용해야 해. 예: 수정 워크플로 단계.

특정 워크플로 단계의 jobUID를 Phrase 애플리케이션에서 검색하려면 다음 단계를 따라:
1. 프로젝트를 열어.
2. 작업 테이블에서 완료된 파일을 다운로드하려는 워크플로 단계로 전환해.
3. 브라우저에서 /job 이후의 URL의 고유 부분을 복사해.
사용해 작업 목록 API 호출

이 엔드포인트는 지정된 프로젝트 내의 작업 목록을 반환해. workflowLevel 쿼리 매개변수를 사용해 호출해. 이 매개변수는 반환된 작업이 속한 워크플로 단계를 나타내는 0이 아닌 값의 매개변수야. 지정하지 않으면 기본적으로 값이 1 (= 첫 번째 워크플로 단계)로 설정돼. 예를 들어, 수정 단계의 작업을 가져와야 하는 경우, 쿼리 매개변수에 해당 단계의 번호를 지정해. 즉, 2이야.

다운로드 대상 파일(비동기) 호출은 번역이 포함된 대상 파일을 생성하고 다운로드하는 비동기 요청을 시작해. 응답 내에서 직접적으로 대상 파일을 제공하지 않지만, 다음 호출에 필요한 asyncRequestId를 제공해.

메서드

PUT
요청 URL

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
응답

AsyncRequest ID

응답에서 asyncRequestID와 함께 비동기 요청 가져오기를 사용해 요청이 완료되었는지 확인해. 비동기 요청이 완료되면, 비동기 요청을 기반으로 한 대상 파일 다운로드 호출을 사용해 대상 파일을 다운로드할 수 있어. asyncRequestId는 한 번만 사용할 수 있어. 다운로드가 시작되면, asyncRequestId는 더 이상 사용할 수 없어.

메서드

GET
요청 URL

https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/downloadTargetFile/1291716982
응답

완료된 파일 자체에 대한 이진 응답

프로젝트를 완료로 설정

프로젝트에서 작업이 완료되면, 프로젝트 상태 편집 호출을 사용해 필수 매개변수 projectUid와 상태를 사용해 전체 프로젝트의 상태를 완료로 변경해. 이 변경은 수동으로 이루어지지만, 프로젝트 상태 자동화가 사용되면 상태가 자동으로 변경돼. 콜백 수신에 따라 다른 작업을 시작하기 위해 웹 후크를 기다리는 것도 가능해.

메서드

POST
요청 URL

https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
요청 본문
```
{ "상태": "완료"}
```
응답

비어 있음 (상태 204: 컨텐츠 없음)