使用者¶

• 目錄
• 使用者
  • /users.:format
    • GET
    • POST
  • /users/:id.:format
    • GET
    • PUT
    • DELETE
  • 另請參閱

/users.:format¶

GET¶

返回使用者列表。

此端點需要管理員權限。

範例:

GET /users.xml

可選篩選器

• status：僅取得具有指定狀態的使用者。請參閱 app/models/principal.rb 以取得可用狀態列表。提供空值以匹配所有使用者，無論其狀態為何。預設值為 1（活動使用者）。 可能的值為
  • 1：活動中（使用者可以登入並使用其帳戶）
  • 2：已註冊（使用者已註冊但尚未確認其電子郵件地址或尚未由管理員啟用。使用者無法登入）
  • 3：已鎖定（使用者曾經處於活動狀態，現在已被鎖定，使用者無法登入）
• name：根據登入名、名字、姓氏和電子郵件地址篩選使用者；如果模式包含空格，它也會返回名字匹配第一個單字或姓氏匹配第二個單字的使用者。
• group_id：僅取得屬於指定群組的使用者

POST¶

建立使用者。

此端點需要管理員權限。

參數:

• user（必填）：使用者屬性的雜湊，包含
  • login（必填）：使用者登入名
  • password：使用者密碼
  • firstname（必填）
  • lastname（必填）
  • mail（必填）
  • auth_source_id：驗證模式 ID
  • mail_notification：only_my_events、none 等。
  • must_change_passwd：true 或 false
  • generate_password：true 或 false
  • custom_fields - 請參閱 自訂欄位
• send_information：true 或 false：將帳戶資訊傳送給使用者

範例:

POST /users.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<user>
  <login>jplang</login>
  <firstname>Jean-Philippe</firstname>
  <lastname>Lang</lastname>
  <password>secret</password>
  <mail>jp_lang@yahoo.fr</mail>
  <auth_source_id>2</auth_source_id>
</user>

JSON

{
    "user": {
        "login": "jplang",
        "firstname": "Jean-Philippe",
        "lastname": "Lang",
        "mail": "jp_lang@yahoo.fr",
        "password": "secret" 
    }
}

回應:

• 201 Created：使用者已建立
• 422 Unprocessable Entity：由於驗證失敗，使用者未建立（回應主體包含錯誤訊息）

/users/:id.:format¶

GET¶

返回使用者詳細資訊。您可以使用 /users/current.:format 來取得用於存取 API 的使用者憑證。

此端點可由管理員或非管理員使用，但返回的欄位將取決於請求使用者的權限（請參閱下方的回應）。

參數:

• include（可選）：以逗號分隔的關聯列表，包含在回應中
  • memberships：新增有關使用者在專案上的成員資格和角色的額外資訊
  • groups（於 2.1 版新增）: 新增關於使用者群組的額外資訊

範例:

GET /users/current.xml

回傳當前使用者的詳細資訊。

GET /users/3.xml?include=memberships,groups

回傳使用者 ID 3 的詳細資訊，以及關於使用者專案成員資格的額外詳細資訊。

回應:

<user>
  <id>3</id>
  <login>jplang</login>
  <firstname>Jean-Philippe</firstname>
  <lastname>Lang</lastname>
  <mail>jp_lang@yahoo.fr</mail>
  <created_on>2007-09-28T00:16:04+02:00</created_on>
  <updated_on>2010-08-01T18:05:45+02:00</updated_on>
  <last_login_on>2011-08-01T18:05:45+02:00</last_login_on>
  <passwd_changed_on>2011-08-01T18:05:45+02:00</passwd_changed_on>
  <api_key>ebc3f6b781a6fb3f2b0a83ce0ebb80e0d585189d</api_key>
  <avatar_url></avatar_url>
  <status>1</status>
  <custom_fields type="array" />
  <memberships type="array">
    <membership>
      <project name="Redmine" id="1"/>
      <roles type="array">
        <role name="Administrator" id="3"/>
        <role name="Contributor" id="4"/>
      </roles>
    </membership>
  </memberships>
  <groups type="array">
    <group id="20" name="Developers"/>
  </groups>
</user>

如果發出請求的使用者不是管理員，則取決於被請求的使用者

• 如果使用者未被鎖定且不是管理員，則端點會回傳一個使用者物件，其中包含 firstname、lastname、mail、created_on 欄位
• 如果使用者未被鎖定且是管理員，則端點會回傳一個使用者物件，其中包含 firstname、lastname、created_on、last_login_on 欄位
• 如果使用者已被鎖定，則端點會回傳 404 狀態碼
• 如果使用者是發出請求的使用者，您還將擁有 login、api_key 欄位

如果發出請求的使用者是管理員，則始終會回傳使用者物件（無論是否被封鎖）。它將包含更多詳細資訊

• api_key：使用者的 API 金鑰，對管理員和您自己可見（於 2.3.0 版新增）
• status：代表使用者狀態的數字 ID，僅對管理員可見（於 2.4.0 版新增）。如需可用狀態列表，請參閱 app/models/principal.rb。

PUT¶

更新使用者。

此端點需要管理員權限。

範例:

PUT /users/20.xml

參數:

• user（必填）：使用者屬性的雜湊（與建立使用者時相同）
• admin（選填）：可能的值為 true 或 false，賦予使用者在執行個體中的管理員權限
• custom_fields - 請參閱 自訂欄位

DELETE¶

此端點需要管理員權限。

刪除使用者。

範例:

DELETE /users/20.xml

回應:

• 204 No Content：使用者已刪除

另請參閱¶

• 用於將使用者新增至專案或從專案中移除使用者的 成員資格 API。
• 用於將使用者新增至群組或從群組中移除使用者的 群組 API。