memoQ： Server Resources API文檔

當(dāng)前文檔為您提供了界面的一般概述，還包括詳細(xì)介紹每個(gè)服務(wù)和所有操作的參考。

• 界面概述
• API 參考

 

1. 概述

1.1. 簡介

memoQ 服務(wù)器資源 API 是一個(gè) REST 風(fēng)格的接口，用于由 memoQ 服務(wù)器提供的一組功能。 這個(gè)接口使 memoQ 服務(wù)器可以從多種客戶端應(yīng)用程序訪問，讓它們成為桌面、移動(dòng)或 Web 應(yīng)用程序。 客戶端只需要發(fā)送簡單、易于組裝的 HTTP 請求并使用響應(yīng)。 在客戶端和服務(wù)器之間來回傳輸?shù)男畔⑼ǔＪ?JSON 序列化的。 目前，該 API 支持操作翻譯記憶庫 (TM) 和術(shù)語庫 (TB)。

 

TM 支持以下操作：

• 獲取 memoQ 服務(wù)器中的 TM 列表
• 獲取某個(gè) TM 的詳細(xì)信息
• 在 TM 中執(zhí)行相關(guān)搜索
• 在 TM 中查找句段
• 獲取、更新、創(chuàng)建或刪除 TM 中的條目

 

TB 支持以下操作：

• 獲取 memoQ 服務(wù)器中的 TB 列表
• 獲取有關(guān)某個(gè)結(jié)核病的詳細(xì)信息
• 在 TB 中查找術(shù)語
• 獲取、更新、創(chuàng)建或刪除 TB 中的條目
• 獲取 TB 的元數(shù)據(jù)模式

 

在響應(yīng)中，您將返回以 JSON 序列化的 TM 列表：

[

    {

        "AccessLevel": 1,

        "Client": "client 1",

        "Domain": "domain 1",

        "Subject": "subject 1",

        "Project": "project 1",

        "NumEntries": 0,

        "FriendlyName": "Test TM 1",

        "SourceLangCode": "eng",

        "TargetLangCode": "hun",

        "TMGuid": "dea956bd-52ce-4fd5-a666-cb28ddefb090",

        "TMOwner": "csiri"

    },

    {

        "AccessLevel": 1,

        "Client": "client 2",

        "Domain": "domain 2",

        "Subject": "subject 2",

        "Project": "project 2",

        "NumEntries": 0,

        "FriendlyName": "Test TM 2",

        "SourceLangCode": "ger",

        "TargetLangCode": "spa",

        "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",

        "TMOwner": "csiri"

    }

]

 

1.2. 數(shù)據(jù)表示

API 操作的參數(shù)可能來自兩個(gè)地方。 一些參數(shù)是 URL 的一部分，其他參數(shù)被放置在請求的正文中。 API 參考明確指定了所有可能的參數(shù)（包括它們的預(yù)期位置）和所有操作的返回類型。 作為規(guī)則，用于標(biāo)識資源（例如 TM 條目）的參數(shù)是 URL 的一部分，所有其他參數(shù)（如果有）都放在正文中。 身份驗(yàn)證令牌是一個(gè)例外，因?yàn)樗且粋€(gè)通用參數(shù)。 您可以將其放入 URL，但最佳做法是將其放入 HTTP 標(biāo)頭中（見下文）。

API 支持 JSON 序列化作為 HTTP 正文中請求和響應(yīng)的數(shù)據(jù)表示。 這意味著客戶端發(fā)布的數(shù)據(jù)應(yīng)該是 JSON 序列化的。 服務(wù)器返回的數(shù)據(jù)也是 JSON 序列化的。

客戶端需要正確設(shè)置 Accept 和 Content-type HTTP 標(biāo)頭。

 

• “Accept: application/json”反映客戶端希望響應(yīng)是 JSON 序列化的。
• “Content-type:application/json”表示客戶端發(fā)布的數(shù)據(jù)是JSON序列化的。

 

1.3. 安全

1.3.1. 身份驗(yàn)證和會話處理

只有在 memoQ 服務(wù)器用戶成功登錄后才能訪問 API 的操作。 登錄將為您提供一個(gè)身份驗(yàn)證令牌，您需要在所有即將到來的請求中提供該令牌。 從技術(shù)上講，此訪問令牌可識別您與 memoQ 服務(wù)器的用戶會話。 令牌可以作為查詢字符串參數(shù)包含在 URL 中，也可以放入 Authorization HTTP 標(biāo)頭中。

要登錄到 memoQ 服務(wù)器，您需要向以下 URL 發(fā)送 HTTP POST 請求，請求正文包含您要使用的憑據(jù)和身份驗(yàn)證類型。

 

在響應(yīng)中，您將獲得身份驗(yàn)證令牌：

Response body:

{

    "Name": "admin",

    "Sid": "00000000-0000-0000-0001-000000000001",

    "AccessToken": "fde0f7ed-d585-48ec-a0a9-397aea195ccd"

}

 

您現(xiàn)在可以將令牌作為查詢字符串參數(shù)附加到 URL

或者您可以將其放入 Authorization HTTP 標(biāo)頭中：

Authorization: MQS-API fde0f7ed-d585-48ec-a0a9-397aea195ccd

API 支持您可以與 memoQ 服務(wù)器一起使用的所有用戶類型：

 

• MemoQServerUser (0)：使用在 memoQ 服務(wù)器上創(chuàng)建的用戶名和密碼登錄。

 

示例請求：

{

    username: "admin",

    password: "secret",

    LoginMode: "0"

}

 

• WindowsUser (1)：通過指定從 AD 或 SAM 同步的用戶的用戶名和密碼登錄。

·

示例請求：

{

    username: "mydomain\testuser",

    password: "secret",

    LoginMode: "1"

}

 

• LTUser (2)：使用從語言終端同步的用戶進(jìn)行單點(diǎn)登錄。 登錄請求應(yīng)包含服務(wù) URL“http://memoqserver”的 CAS (https://wiki.jasig.org/display/CAS/Home) 服務(wù)票證。

·

示例請求：

{

    LTST: "",

    LoginMode: "2"

}

 

 

用戶的會話過期并且令牌在一段時(shí)間不活動(dòng)后失效。 客戶端通過專用錯(cuò)誤 (ErrorCode: InvalidOrExpiredToken) 收到通知。 會話到期后需要重新登錄。

 

也可以通過調(diào)用 Logout 手動(dòng)終止會話

 

1.3.2. 授權(quán)

 

對資源（TM 和 TB）的訪問由 API 用戶的組成員控制。 memoQ 包含兩個(gè)內(nèi)置組，稱為“通過 API/插件查找資源”和“通過 API/插件更新資源”。 這兩個(gè)組的成員資格自動(dòng)授予對 memoQ 服務(wù)器上所有資源的查找和更新權(quán)限。

通過在 HttpApiConfig.xml 文件中指定以下標(biāo)志，可以覆蓋此行為并強(qiáng)制執(zhí)行默認(rèn)資源訪問策略：

true

當(dāng)用戶無權(quán)訪問請求的資源時(shí)，她會返回一個(gè)專門的錯(cuò)誤（錯(cuò)誤代碼：未授權(quán)）。

 

1.3.3. 許可

訪問 API 需要 Translator light 或 Translator Pro 許可證。 首先，它會嘗試檢索 Translator Light 許可證，當(dāng)沒有 Translator Light 許可證時(shí)，它會嘗試獲取 Translator Pro。 當(dāng)池中既沒有l(wèi)ight 也沒有pro 許可證時(shí)，用戶將收到一個(gè)專門的錯(cuò)誤（錯(cuò)誤代碼：NoLicenseAvailable）并且在返回許可證之前將無法使用該 API。

處理許可證對客戶端是透明的，memoQ 服務(wù)器以按需方式請求許可證，并在一段時(shí)間不活動(dòng)后釋放它們。 此超時(shí)比會話超時(shí)短。 許可證的生命周期和會話沒有綁定在一起。 因此，您應(yīng)該為所有請求中的許可錯(cuò)誤做好準(zhǔn)備。

 

1.3.4. HTTPS

出于安全原因，API 僅支持 HTTPS。

 

1.4. 錯(cuò)誤處理

請求的成功通過響應(yīng)的 HTTP 狀態(tài)碼反映出來。 如果成功，則為 2xx（200 OK、201 Created 或 204 No Content）。 否則在執(zhí)行請求期間出現(xiàn)錯(cuò)誤。 如果出現(xiàn)錯(cuò)誤，響應(yīng)還包含有關(guān)錯(cuò)誤的 JSON 結(jié)構(gòu)，該結(jié)構(gòu)為您提供比 HTTP 狀態(tài)代碼更多的信息。

錯(cuò)誤響應(yīng)的一般形式是：

{

    "ErrorCode": "InvalidOrExpiredToken",

    "Message": "Security token is invalid or has expired."

}

ErrorCode 是標(biāo)識問題的字符串常量，Message 是一些英文（非本地化）文本信息，可為您提供更多詳細(xì)信息。

 

下表總結(jié)了 API 客戶端應(yīng)準(zhǔn)備的所有錯(cuò)誤。

HTTP 狀態(tài)代碼	錯(cuò)誤代碼	消息
401 未授權(quán)	認(rèn)證失敗	用戶無法通過身份驗(yàn)證。
401 未授權(quán)	無效或過期令牌	安全令牌無效、已過期或從請求中丟失。
401 未授權(quán)	太頻繁登錄	注銷后登錄過于頻繁
401 未授權(quán)	無許可證可用	無法申請?jiān)S可證。
403 禁止	未授權(quán)	用戶未授權(quán)訪問資源。
404 未找到	資源未找到	在服務(wù)器上找不到資源
404 未找到	未找到條目	在服務(wù)器上找不到資源的條目。
409 沖突	樂觀并發(fā)錯(cuò)誤	有人修改了該條目。
400 錯(cuò)誤的請求	TBExclusion錯(cuò)誤	不能執(zhí)行該操作。TB是開放的，供專用的（例如用于編輯）。
400 錯(cuò)誤的請求	TB只讀錯(cuò)誤	不能執(zhí)行該操作。TB是只讀的。
400 錯(cuò)誤的請求	不支持反向查找	TM不支持反向查詢。
400 錯(cuò)誤的請求	無效參數(shù)	這些參數(shù)是無效的。
400 錯(cuò)誤的請求	自定義MetaError	未找到自定義元定義。
500 內(nèi)部服務(wù)器錯(cuò)誤	內(nèi)部錯(cuò)誤	服務(wù)器發(fā)生內(nèi)部錯(cuò)誤。 檢查日志以獲取詳細(xì)信息。

 

1.5. 服務(wù)版本控制

目前該 API 包含三個(gè)服務(wù)。 他們每個(gè)人都有一個(gè)專用的 URL 和一個(gè)版本號。 版本號可能因服務(wù)而異。

服務(wù)：

• 認(rèn)證服務(wù)

URL: /memoqserverhttpapi/v1/auth

當(dāng)前版本：v1

• 翻譯記憶服務(wù)

URL: /memoqserverhttpapi/v1/tms

當(dāng)前版本：v1

• 術(shù)語庫服務(wù)

URL: /memoqserverhttpapi/v1/tbs

當(dāng)前版本：v1

1.6. 例子

以下示例顯示了對 TM 的一些操作。

 

登錄 memoQ 服務(wù)器

 

要求：

POST memoqserverhttpapi/v1/auth/login

{

    username: "admin",

    password: "secret",

    LoginMode: "0"

}

 

回復(fù)：

{

    "Name": "admin",

    "Sid": "00000000-0000-0000-0001-000000000001",

    "AccessToken": "803be2ac-f4a1-4b47-abea-8b12f2a172d8"

}

 

列出所有 TM

 

要求：

GET memoqserverhttpapi/v1/tms?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

 

回復(fù)：

[

    {

        "AccessLevel": 1,

        "Client": "client 1",

        "Domain": "domain 1",

        "Subject": "subject 1",

        "Project": "project 1",

        "NumEntries": 0,

        "FriendlyName": "Test TM 1",

        "SourceLangCode": "eng",

        "TargetLangCode": "hun",

        "TMGuid": "dea956bd-52ce-4fd5-a666-cb28ddefb090",

        "TMOwner": "csiri"

    },

    {

        "AccessLevel": 1,

        "Client": "client 2",

        "Domain": "domain 2",

        "Subject": "subject 2",

        "Project": "project 2",

        "NumEntries": 0,

        "FriendlyName": "Test TM 2",

        "SourceLangCode": "ger",

        "TargetLangCode": "spa",

        "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",

        "TMOwner": "csiri"

    }

]

 

獲取有關(guān) TM 的信息

 

要求：

GET memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

 

回復(fù)：

{

    "AccessLevel": 1,

    "Client": "client 2",

    "Domain": "domain 2",

    "Subject": "subject 2",

    "Project": "project 2",

    "NumEntries": 0,

    "FriendlyName": "Test TM 2",

    "SourceLangCode": "ger",

    "TargetLangCode": "spa",

    "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",

    "TMOwner": "csiri"

}

 

向 TM 添加新條目

 

要求：

POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/create?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

{

    "Modifier": "testuser",

    "SourceSegment": "Második szegmens",

    "TargetSegment": "Second segment"

}

 

獲取 TM 的條目

 

要求：

GET memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

 

回復(fù)：

{

    "Client": "",

    "ContextID": null,

    "Created": "2015-10-15T12:45:49.209Z",

    "Creator": "admin",

    "Document": "",

    "Domain": "",

    "FollowingSegment": "",

    "Key": 0,

    "Modified": "2015-10-15T12:45:49.209Z",

    "Modifier": "admin",

    "PrecedingSegment": "",

    "Project": "",

    "SourceSegment": "Második szegmens",

    "Subject": "",

    "TargetSegment": "Second segment",

    "CustomMetas": []

}

 

更新 TM 的條目

 

要求：

POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0/update?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

{

    "Modifier": "testuser",

    "Modified": "2015-10-15T12:45:49.209Z",

    "SourceSegment": "Második szegmens",

    "TargetSegment": "Second segment updated"

}

 

在 TM 中查找句段

 

要求：

POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/lookupsegments?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

{

    "Segments": [

        {

            "Segment": "Második"

        }

    ]

}

 

回復(fù)：

{

    "Result": [

        {

            "TMHits": [

                {

                    "MatchRate": 58,

                    "TransUnit": {

                        "Client": "",

                        "ContextID": null,

                        "Created": "0001-01-01T00:00:00Z",

                        "Creator": "",

                        "Document": "",

                        "Domain": "",

                        "FollowingSegment": "",

                        "Key": 0,

                        "Modified": "2015-10-15T12:52:37.781Z",

                        "Modifier": "admin",

                        "PrecedingSegment": "",

                        "Project": "",

                        "SourceSegment": "Második szegmens",

                        "Subject": "",

                        "TargetSegment": "Second segment updated",

                        "CustomMetas": []

                    }

                }

            ]

        }

    ]

}

 

備注：出于性能原因，操作當(dāng)前未在返回的 TMHits 對象的 TransUnit 字段的上下文相關(guān)字段（ContextID、PrecedingSegment、FollowSegment）中返回有效值。 這些信息可以通過發(fā)出一個(gè)額外的請求來檢索，該請求基于其密鑰獲取特定的 TM 條目。

 

TM 中的相關(guān)搜索

要求：

POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/concordance?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

{

    "SearchExpression": ["második"]

}

回復(fù)：

{

    "ConcResult": [

        {

            "ConcordanceTextRanges": [

                {

                "Length": 7,

                "Start": 0

                }

            ],

            "ConcordanceTranslationRanges": [],

            "Length": 7,

            "StartPos": 0,

            "TMEntry": {

                "SourceSegment": "Második szegmens",

                "TargetSegment": "Second segment updated"

            }

        }

    ],

    "ConcTransResult": [],

    "Errors": [],

    "TotalConcResult": 1

}

刪除 TM 的條目

要求：

POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0/delete?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

 

2. API 參考

2.1. 驗(yàn)證

負(fù)責(zé)用戶認(rèn)證。 使用戶能夠登錄和注銷 memoQ 服務(wù)器。

API	描述
POST v1/auth/login	使用 memoQ 服務(wù)器、Windows 或語言終端用戶登錄 memoQ 服務(wù)器。 它在 memoQ 服務(wù)器上為用戶創(chuàng)建一個(gè)會話。
POST v1/auth/logout	從 memoQ 服務(wù)器注銷當(dāng)前用戶。 它從 memoQ 服務(wù)器中刪除用戶的會話。

 

2.2. 翻譯記憶庫

 

負(fù)責(zé)翻譯記憶庫相關(guān)的動(dòng)作。

 

API	描述
GET v1/tms?srcLang={srcLang}&targetLang={targetLang}	獲取 memoQ 服務(wù)器上的翻譯記憶庫列表。 按指定的源語言或目標(biāo)語言過濾 TM。
GET v1/tms?tmGuid={tmGuid}	獲取指定 Guid 的翻譯記憶庫。
GET v1/tms/{tmGuid}	獲取指定 Guid 的翻譯記憶庫。
GET v1/tms/{tmGuid}/custommetascheme	獲取由 Guid 指定的翻譯記憶庫的自定義元方案。
POST v1/tms/{tmGuid}/concordance	在 Guid 指定的翻譯記憶庫中執(zhí)行相關(guān)搜索。
POST v1/tms/{tmGuid}/lookupsegments	在 Guid 指定的翻譯記憶庫中執(zhí)行查找操作。 備注：出于性能原因，該操作當(dāng)前未在返回的 TMHits 對象的 TransUnit 字段的上下文相關(guān)字段（ContextID、PrecedingSegment、FollowSegment）中返回有效值。 這些信息可以通過發(fā)出一個(gè)額外的請求來檢索，該請求基于其密鑰獲取特定的 TM 條目。
GET v1/tms/{tmGuid}/entries/{entryId}	獲取由 TM Guid 和條目 ID 指定的翻譯記憶庫條目。
POST v1/tms/{tmGuid}/entries/{entryId}/update	更新由 TM Guid 和條目 ID 指定的翻譯記憶庫條目。
POST v1/tms/{tmGuid}/entries/create	在 Guid 指定的 TM 中創(chuàng)建翻譯記憶庫條目。
POST v1/tms/{tmGuid}/entries/{entryId}/delete	刪除由 TM Guid 和條目 ID 指定的翻譯記憶庫條目。

 

2.3. 術(shù)語庫

負(fù)責(zé)術(shù)語庫相關(guān)操作。

API	描述
GET v1/tbs?lang[0]={lang[0]}&lang[1]={lang[1]}	獲取 memoQ 服務(wù)器上的術(shù)語庫列表。 按指定的語言過濾 TB。
GET v1/tbs?tbGuid={tbGuid}	按指定的 Guid 獲取術(shù)語庫。
GET v1/tbs/{tbGuid}	按指定的 Guid 獲取術(shù)語庫。
GET v1/tbs/{tbGuid}/metadefinitions	獲取由 Guid 指定的術(shù)語庫的元定義。
POST v1/tbs/{tbGuid}/lookupterms	在 Guid 指定的術(shù)語庫中執(zhí)行查找操作。
POST v1/tbs/{tbGuid}/search	在術(shù)語庫中查找給定的表達(dá)式。
GET v1/tbs/{tbGuid}/entries/{entryId}	獲取由 TB Guid 和條目 ID 指定的術(shù)語庫條目。
POST v1/tbs/{tbGuid}/entries/{entryId}/update	更新由 TB Guid 和條目 ID 指定的術(shù)語庫條目。
POST v1/tbs/{tbGuid}/entries/create?returnNewEntry={returnNewEntry}	在 Guid 指定的 TB 中創(chuàng)建術(shù)語庫條目。
POST v1/tbs/{tbGuid}/entries/{entryId}/delete	刪除由 TB Guid 和條目 ID 指定的術(shù)語庫條目。
GET v1/tbs/{tbGuid}/entries/{entryId}/entrymetas/{metaname}	獲取術(shù)語庫條目的入門級元屬性的圖像。
GET v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{metaname}	獲取術(shù)語庫條目的語言級別元屬性的圖像。
GET v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{language}/{metaname}	獲取術(shù)語庫條目的語言級別元屬性的圖像。
GET v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{metaname}	獲取術(shù)語庫條目的術(shù)語級別元屬性的圖像。
GET v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{termId}/{metaname}	獲取術(shù)語庫條目的術(shù)語級別元屬性的圖像。
POST v1/tbs/{tbGuid}/entries/{entryId}/entrymetas/{metaname}	設(shè)置術(shù)語庫條目的條目級元屬性的圖像。
POST v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{metaname}	設(shè)置術(shù)語庫條目的語言級別元屬性的圖像。
POST v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{language}/{metaname}	設(shè)置術(shù)語庫條目的語言級別元屬性的圖像。
POST v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{metaname}	設(shè)置術(shù)語庫條目的術(shù)語級別元屬性的圖像。
POST v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{termId}/{metaname}	設(shè)置術(shù)語庫條目的術(shù)語級別元屬性的圖像。