memoQ： Server Resources API文檔

當前文檔為您提供了界面的一般概述，還包括詳細介紹每個服務和所有操作的參考。

• 界面概述
• API 參考

 

1. 概述

1.1. 簡介

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

 

TM 支持以下操作：

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

 

TB 支持以下操作：

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

 

在響應中，您將返回以 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ù)據表示

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

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

客戶端需要正確設置 Accept 和 Content-type HTTP 標頭。

 

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

 

1.3. 安全

1.3.1. 身份驗證和會話處理

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

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

 

在響應中，您將獲得身份驗證令牌：

Response body:

{

    "Name": "admin",

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

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

}

 

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

或者您可以將其放入 Authorization HTTP 標頭中：

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

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

 

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

 

示例請求：

{

    username: "admin",

    password: "secret",

    LoginMode: "0"

}

 

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

·

示例請求：

{

    username: "mydomain\testuser",

    password: "secret",

    LoginMode: "1"

}

 

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

·

示例請求：

{

    LTST: "",

    LoginMode: "2"

}

 

 

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

 

也可以通過調用 Logout 手動終止會話

 

1.3.2. 授權

 

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

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

true

當用戶無權訪問請求的資源時，她會返回一個專門的錯誤（錯誤代碼：未授權）。

 

1.3.3. 許可

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

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

 

1.3.4. HTTPS

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

 

1.4. 錯誤處理

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

錯誤響應的一般形式是：

{

    "ErrorCode": "InvalidOrExpiredToken",

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

}

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

 

下表總結了 API 客戶端應準備的所有錯誤。

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

 

1.5. 服務版本控制

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

服務：

• 認證服務

URL: /memoqserverhttpapi/v1/auth

當前版本：v1

• 翻譯記憶服務

URL: /memoqserverhttpapi/v1/tms

當前版本：v1

• 術語庫服務

URL: /memoqserverhttpapi/v1/tbs

當前版本：v1

1.6. 例子

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

 

登錄 memoQ 服務器

 

要求：

POST memoqserverhttpapi/v1/auth/login

{

    username: "admin",

    password: "secret",

    LoginMode: "0"

}

 

回復：

{

    "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

 

回復：

[

    {

        "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"

    }

]

 

獲取有關 TM 的信息

 

要求：

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

 

回復：

{

    "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

 

回復：

{

    "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"

        }

    ]

}

 

回復：

{

    "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": []

                    }

                }

            ]

        }

    ]

}

 

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

 

TM 中的相關搜索

要求：

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

{

    "SearchExpression": ["második"]

}

回復：

{

    "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. 驗證

負責用戶認證。 使用戶能夠登錄和注銷 memoQ 服務器。

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

 

2.2. 翻譯記憶庫

 

負責翻譯記憶庫相關的動作。

 

API	描述
GET v1/tms?srcLang={srcLang}&targetLang={targetLang}	獲取 memoQ 服務器上的翻譯記憶庫列表。 按指定的源語言或目標語言過濾 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í)行相關搜索。
POST v1/tms/{tmGuid}/lookupsegments	在 Guid 指定的翻譯記憶庫中執(zhí)行查找操作。 備注：出于性能原因，該操作當前未在返回的 TMHits 對象的 TransUnit 字段的上下文相關字段（ContextID、PrecedingSegment、FollowSegment）中返回有效值。 這些信息可以通過發(fā)出一個額外的請求來檢索，該請求基于其密鑰獲取特定的 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. 術語庫

負責術語庫相關操作。

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