著者DB機能API

1. 目的

著者DBをAPIで操作できるようにする。

2. 要求仕様

著者DBを検索、登録、更新、削除するためのAPIを整備する。
検索APIでは、検索キーとして、著者姓名、著者名、著者姓、著者識別子を利用できるようにする。
検索結果には著者DBの各項目を含める。
検索、登録、更新、削除のAPIでそれぞれ固有のスコープを必須とする。
サービス用アカウントによるサーバ間OAuth2を利用する。

3. エンドポイント一覧

項番	概要	HTTP Method	エンドポイント	スコープ
1	著者DB著者検索	GET	/api/{version}/authors	author:search
2	著者DB著者追加	POST	/api/{version}/authors	author:create
3	著者DB著者編集	PUT	/api/{version}/authors/{identifier}	author:update
4	著者DB著者削除	DELETE	/api/{version}/authors/{identifier}	author:delete

4. スコープと利用可能なロールの関係

APIを利用できるかどうかをスコープ及びスコープに紐づけられた権限で制御する。

スコープ	システム管理者	リポジトリ管理者	コミュニティ管理者	登録ユーザ	一般ユーザ	ゲスト（未ログイン）
author:search	〇	〇	〇	✕	✕	✕
author:create	〇	〇	〇	✕	✕	✕
author:update	〇	〇	〇	✕	✕	✕
author:delete	〇	〇	〇	✕	✕	✕

5. 著者DB検索

5.1. 機能内容

OAuth2認証機能を用いてユーザーの適切なアクセス制限を行う。
指定された検索キーで著者DBを検索した結果を返す。
検索キーとして著者姓名、著者名、著者姓、著者識別子（外部識別子を含む）、コミュニティIDを利用できる。
スコープとロールによるアクセス制御を行う。
著者識別子種別と属機関識別子種別はidではなくschemeの値でリクエスト、レスポンスをする

5.2. API仕様

関連モジュール

weko_authors.rest.py
weko_authors.scopes.py
weko_authors.config.py

エンドポイント

GET /api/{version}/authors

スコープ

author:search

リクエスト

パスパラメータ

| 項目 | 説明 | | --- | --- | | version | APIのバージョン |
クエリパラメータ
- idtypeは文字列で指定させる（例：weko、orcid）
  
  | 項目 | 説明 | | --- | --- | |fullname|著者姓名| |firstname|著者名| |familyname|著者姓| |idtype|著者識別子種別。選択肢は画面と同様| |authorid|idtypeに対応した著者識別子| |communityid|著者を管理するコミュニティのID|
ヘッダーパラメータ

| 項目 | 値 | 必須 | 説明 | | --- | --- | --- | --- | | Authorization | Bearer | - |操作するWEKOユーザーのOAuth認証情報。アクセストークンを用いる。|

レスポンス

レスポンスコード

| コード | 説明 | | --- | --- | | 200 | 正常終了 | | 400 | リクエストに不備がある | | 401 | OAuth2認証失敗 | | 403 | 該当ユーザに必要なロールが付与されていない| | 500 | 内部のエラー |

レスポンスボディ

サンプル

  {
      "authors": [
          {
              "emailInfo": [
                  {
                      "email": "sample@xxx.co.jp"
                  }
              ],
              "authorIdInfo": [
                  {
                      "idType": "ORCID",
                      "authorId":"https://orcid.org/##",
                      "authorIdShowFlg": "true"
                  }
              ],
              "authorNameInfo": [
                  {
                      "language": "en",
                      "firstName": "John",
                      "familyName": "Doe",
                      "nameFormat": "familyNmAndNm",
                      "nameShowFlg": "true"
                  }
              ],
              "affiliationInfo": [
                  {
                      "identifierInfo": [
                          {
                              "affiliationId": "https://ror.org/##",
                              "affiliationIdType": "ROR",
                              "identifierShowFlg": "true"
                          }
                      ],
                      "affiliationNameInfo": [
                          {
                              "affiliationName": "NII",
                              "affiliationNameLang": "en",
                              "affiliationNameShowFlg": "true"
                          }
                      ],
                      "affiliationPeriodInfo": [
                          {
                              "periodStart": "2025-01-27",
                              "periodEnd": "2025-03-21"
                          }
                      ]
                  }
              ],
              "communityIds": ["community1"]
          }
      ]
  }

データ構造

|項目名|型|説明| | --- | --- | --- | |authors|object|変更情報を格納する。|

emailInfo

|項目名|型|説明| | --- | --- | --- | |email|string|著者のメールアドレス|

authorIdInfo

idtypeは文字列に変換して返す（例：weko、orcid）

|項目名|型|説明| | --- | --- | --- | |idType|string|著者識別子種別。選択肢は画面と同様| |authorId|string|著者識別子| |authorIdShowFlg|boolean|［著者DBから入力］機能で、外部著者IDを自動入力するかどうか。|

authorNameInfo

|項目名|型|説明| | --- | --- | --- | |language|string|著者姓名の記述言語。選択肢は画面と同様| |firstname|string|著者名| |familyName|string|著者姓| |nameFormat|string|著者名と著者姓の組み合わせ方| |nameShowFlg|boolean|［著者DBから入力］機能で、氏名が自動入力されるかどうか。|

identifierInfo
affiliationIdTypeは文字列に変換して返す（例：ISNI、ROR）

|項目名|型|説明| | --- | --- | --- | |affiliationIdType|string|所属機関識別子種別。選択肢は画面と同様| |affiliationId|string|所属機関識別子| |identifierShowFlg|boolean||

affiliationNameInfo

|項目名|型|説明| | --- | --- | --- | |affiliationName|string|所属機関名| |affiliationNameLang|string|所属機関の記述言語。選択肢は画面と同様| |affiliationNameShowFlg|boolean||

affiliationPeriodInfo

|項目名|型|説明| | --- | --- | --- | |periodStart|string|所属開始日。入力形式はyyyy-MM-dd。| |periodEnd|string|所属終了日。入力形式はyyyy-MM-dd。|

communityIds

|項目名|型|説明| | --- | --- | --- | |communityIds[n]|string|著者を管理するコミュニティのID|

5.3. 処理概要

ユーザー認証する
- リクエストに Authorization ヘッダーがある場合は、記載されたアクセストークンを使用しユーザーを認証する。認証に失敗した場合は401エラーを返す。
スコープを確認する
- 必要なスコープがついていなければ403エラーを返す。
ユーザーの権限を確認する
- スコープに設定されている権限が満たせていなければ403エラーを返す。
クエリパラメータから検索項目を取得する
- idtypeとauthoridの片方のみが指定された場合は400エラーを返す。エラーメッセージは「Both 'idtype' and 'authorid' must be specified together or omitted.」とする。
- idtypeで指定された識別子種別でauthors_prefix_settingsテーブルのschemeカラムを検索し、一致するもののIDを取得する。
著者情報を検索する
- Elasticsearchに対して取得したパラメータでAND検索する。
- DBとのやりとりでエラーが発生した場合は、ロールバックして500エラーを返す。
検索結果を返す
- 検索結果のidtypeはauthors_prefix_settingsテーブルのidからschemeの値に変換する。
- 検索結果のaffiliationIdTypeはauthors_prefix_settingsテーブルのidからschemeの値に変換する。
- 検索結果を整形してjson形式にエンコードしたものをレスポンスボディに入れ、ステータスコード200を返す。
- 検索結果が空の場合もステータスコード200を返す。

6. 著者DB著者登録

6.1. 機能内容

OAuth2認証機能を用いてユーザーの適切なアクセス制限を行う。
渡された内容で著者を登録する。
スコープとロールによるアクセス制御を行う。
著者識別子種別と属機関識別子種別はidではなくschemeの値でリクエスト、レスポンスをする

6.2. API仕様

関連モジュール

weko_authors.rest.py
weko_authors.scopes.py
weko_authors.config.py

エンドポイント

POST /api/{version}/authors

スコープ

author:create

リクエスト

パスパラメータ

| 項目 | 説明 | | --- | --- | | version | APIのバージョン |
ヘッダーパラメータ

| 項目 | 値 | 必須 | 説明 | | --- | --- | --- | --- | | Authorization | Bearer | - |操作するWEKOユーザーのOAuth認証情報。アクセストークンを用いる。|
リクエストボディ

サンプル
```
  {
      "author": {
          "emailInfo": [
              {
                  "email": "sample@xxx.co.jp"
              }
          ],
          "authorIdInfo": [
              {
                  "idType": "ORCID",
                  "authorId":"https://orcid.org/##",
                  "authorIdShowFlg": "true"
              }
          ],
          "authorNameInfo": [
              {
                  "language": "en",
                  "firstName": "John",
                  "familyName": "Doe",
                  "nameFormat": "familyNmAndNm",
                  "nameShowFlg": "true"
              }
          ],
          "affiliationInfo": [
              {
                  "identifierInfo": [
                      {
                          "affiliationId": "https://ror.org/##",
                          "affiliationIdType": "ROR",
                          "identifierShowFlg": "true"
                      }
                  ],
                  "affiliationNameInfo": [
                      {
                          "affiliationName": "NII",
                          "affiliationNameLang": "en",
                          "affiliationNameShowFlg": "true"
                      }
                  ],
                  "affiliationPeriodInfo": [
                      {
                          "periodStart": "2025-01-27",
                          "periodEnd": "2025-03-21"
                      }
                  ]
              }
          ],
          "communityIds": ["community1"]
      }
  }
```
データ構造

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |author|object|〇|-|変更情報を格納する。|

emailInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |email|string|✕|-|著者のメールアドレス|

authorIdInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |idType|string|△※|-|著者識別子種別。選択肢は画面と同様（例：weko、orcid）| |authorId|string|△※|-|著者識別子| |authorIdShowFlg|boolean|✕|true|［著者DBから入力］機能で、外部著者IDを自動入力するかどうか。|

※ idTypeとauthorIdの片方のみが送られた場合はエラーにする

authorNameInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |language|string|✕※|-|著者姓名の記述言語。選択肢は画面と同様| |firstname|string|✕|-|著者名| |familyName|string|✕|-|著者姓| |nameFormat|string|✕|"familyNmAndNm"※|著者名と著者姓の組み合わせ方| |nameShowFlg|boolean|✕|true|［著者DBから入力］機能で、氏名が自動入力されるかどうか。|

※ firstnameまたはfamilyNameが指定されたときはlanguageは必須とする ※ language、firstname、familyNameが送られてきた場合でnameFormatが指定されていない場合のみデフォルト値を適用する

identifierInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |affiliationIdType|string|△※|-|所属機関識別子種別。選択肢は画面と同様（例：ISNI、ROR）| |affiliationId|string|△※|-|所属機関識別子| |identifierShowFlg|boolean|✕|true||

※ affiliationIdTypeとaffiliationIdの片方のみが送られた場合はエラーにする

affiliationNameInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |affiliationName|string|△※|-|所属機関名| |affiliationNameLang|string|△※|-|所属機関の記述言語。選択肢は画面と同様| |affiliationNameShowFlg|boolean|✕|true||

※ affiliationNameとaffiliationNameLangの片方のみが送られた場合はエラーにする

affiliationPeriodInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |periodStart|string|✕|-|所属開始日。入力形式はyyyy-MM-dd。| |periodEnd|string|✕|-|所属終了日。入力形式はyyyy-MM-dd。|

communityIds

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |communityIds[n]|string|△※|-|著者を管理するコミュニティのID|

※ コミュニティ管理者の場合は管理対象のコミュニティが指定されていない場合はエラーにする

レスポンス

レスポンスコード

| コード | 説明 | | --- | --- | | 200 | 正常終了 | | 400 | リクエストに不備がある | | 401 | OAuth2認証失敗 | | 403 | 該当ユーザに必要なロールが付与されていない| | 500 | 内部のエラー |

レスポンスボディ

サンプル

  {
      "message": "Author successfully registered.",
      "author":{
          "emailInfo": [
              {
                  "email": "sample@xxx.co.jp"
              }
          ],
          "authorIdInfo": [
              {
                  "idType": "ORCID",
                  "authorId":"https://orcid.org/##",
                  "authorIdShowFlg": "true"
              }
          ],
          "authorNameInfo": [
              {
                  "language": "en",
                  "firstName": "John",
                  "familyName": "Doe",
                  "nameFormat": "familyNmAndNm",
                  "nameShowFlg": "true"
              }
          ],
          "affiliationInfo": [
              {
                  "identifierInfo": [
                      {
                          "affiliationId": "https://ror.org/##",
                          "affiliationIdType": "ROR",
                          "identifierShowFlg": "true"
                      }
                  ],
                  "affiliationNameInfo": [
                      {
                          "affiliationName": "NII",
                          "affiliationNameLang": "en",
                          "affiliationNameShowFlg": "true"
                      }
                  ],
                  "affiliationPeriodInfo": [
                      {
                          "periodStart": "2025-01-27",
                          "periodEnd": "2025-03-21"
                      }
                  ]
              }
          ],
          "communityIds": ["community1"]
      }
  }

データ構造

|項目名|型|説明| | --- | --- | --- | |authors|object|変更情報を格納する。|

emailInfo

|項目名|型|説明| | --- | --- | --- | |email|string|著者のメールアドレス|

authorIdInfo

idtypeは文字列に変換して返す（例：weko、orcid）

|項目名|型|説明| | --- | --- | --- | |idType|string|著者識別子種別。選択肢は画面と同様| |authorId|string|著者識別子| |authorIdShowFlg|boolean|［著者DBから入力］機能で、外部著者IDを自動入力するかどうか。|

authorNameInfo

|項目名|型|説明| | --- | --- | --- | |language|string|著者姓名の記述言語。選択肢は画面と同様| |firstName|string|著者名| |familyName|string|著者姓| |nameFormat|string|著者名と著者姓の組み合わせ方| |nameShowFlg|boolean|［著者DBから入力］機能で、氏名が自動入力されるかどうか。|

identifierInfo
affiliationIdTypeは文字列に変換して返す（例：ISNI、ROR）

|項目名|型|説明| | --- | --- | --- | |affiliationIdType|string|所属機関識別子種別。選択肢は画面と同様| |affiliationId|string|所属機関識別子| |identifierShowFlg|boolean||

affiliationNameInfo

|項目名|型|説明| | --- | --- | --- | |affiliationName|string|所属機関名| |affiliationNameLang|string|所属機関の記述言語。選択肢は画面と同様| |affiliationNameShowFlg|boolean||

affiliationPeriodInfo

|項目名|型|説明| | --- | --- | --- | |periodStart|string|所属開始日。入力形式はyyyy-MM-dd。| |periodEnd|string|所属終了日。入力形式はyyyy-MM-dd。|

communityIds

|項目名|型|説明| | --- | --- | --- | |communityIds[n]|string|著者を管理するコミュニティのID|

6.3. 処理概要

ユーザー認証する
- リクエストに Authorization ヘッダーがある場合は、記載されたアクセストークンを使用しユーザーを認証する。認証に失敗した場合は401エラーを返す。
スコープを確認する
- 必要なスコープがついていなければ403エラーを返す。
ユーザーの権限を確認する
- スコープに設定されている権限が満たせていなければ403エラーを返す。
リクエストを確認する
- 必須の項目が送られていない場合は400エラーにする。
- リクエストボディが無かった場合は400エラーにする。
- authorが空だった場合は、400エラーとなりエラーメッセージ「author can not be null.」が返却される。
- 送られてきた値の型が定義と異なる場合は400エラーを返す。
著者情報を確認する
- authorIdInfo.idType、authorNameInfo.language、affiliationInfo.identifierInfo.affiliationIdType、affiliationInfo.affiliationNameInfo.affiliationNameLangの値が選択肢に無い値の場合、400エラーを返す。
- authorIdInfoについて、idTypeとauthorIdの片方のみが送られた場合は400エラーを返す。
- authorNameInfoについて、firstNameまたはfamilyNameが指定されたとき、languageが指定されていなければ400エラーを返す。
- identifierInfoについて、affiliationIdTypeとaffiliationIdの片方のみが送られた場合は400エラーを返す。
- affiliationNameInfoについて、affiliationNameとaffiliationNameLangの片方のみが送られた場合は400エラーを返す。
- affiliationPeriodInfoについて、以下の場合400エラーを返す。
  - yyyy-MM-ddの入力形式を満たさない場合
  - 所属開始日（periodStart）が所属終了日（periodEnd）より後の日付の場合
  - communityIdsについて、以下の場合400エラーを返す。
  - 許可されていない記号や制御文字を使用されている場合
  - DBに存在しないコミュニティIDを指定した場合
  - コミュニティ管理者権限のユーザーで管理対象のコミュニティが一つも含まれていない場合
  - コミュニティ管理者で、いかの場合403エラーを返す。
  - 管理対象外コミュニティのIDを指定した場合
著者情報を登録する
- authorIdInfo.idTypeがWEKOのauthorIdInfo.authorIdに既存のWEKO IDの最大値+1の数字をauthorIdInfo.authorIdとして登録する。
- authorIdInfo.idType、affiliationInfo.identifierInfo.affiliationIdTypeは与えられた値で検索しIDを引っ張ってくる。
- DBとElasticsearchに著者情報を登録する。
- エラーが発生した場合は、ロールバックして500エラーを返す。
レスポンスを返す
- 登録した著者情報をjson形式にエンコードしたものをレスポンスボディに入れ、レスポンスコード200を返す。
- idtypeとaffiliationIdTypeはidではなくschemeの文字列に変換して返す。

7. 著者DB著者変更

7.1. 機能内容

OAuth2認証機能を用いてユーザーの適切なアクセス制限を行う。
指定された著者の情報を送られてきた情報で置き変える。
スコープとロールによるアクセス制御を行う。
著者識別子種別と属機関識別子種別はidではなくschemeの値でリクエスト、レスポンスをする

7.2. API仕様

関連モジュール

weko_authors.rest.py
weko_authors.scopes.py
weko_authors.config.py

エンドポイント

PUT /api/{version}/authors/{identifier}

スコープ

author:update

リクエスト

パスパラメータ

| 項目 | 説明 | | --- | --- | | version | APIのバージョン | | identifier | 更新対象の著者を一意に識別する値。

authorsテーブルのIDまたはElasticSearchのUUID のいずれかを指定する。 |
ヘッダーパラメータ

| 項目 | 値 | 必須 | 説明 | | --- | --- | --- | --- | | Authorization | Bearer | 〇 |操作するWEKOユーザーのOAuth認証情報。アクセストークンを用いる。|
リクエストボディ

サンプル
```
  {
      "force_change": false,
      "author": {
          "emailInfo": [
              {
                  "email": "sample@xxx.co.jp"
              }
          ],
          "authorIdInfo": [
              {
                  "idType": "WEKO",
                  "authorId":"111",
                  "authorIdShowFlg": "true"
              },
              {
                  "idType": "ORCID",
                  "authorId":"https://orcid.org/##",
                  "authorIdShowFlg": "true"
              }
          ],
          "authorNameInfo": [
              {
                  "language": "en",
                  "firstName": "John",
                  "familyName": "Doe",
                  "nameFormat": "familyNmAndNm",
                  "nameShowFlg": "true"
              }
          ],
          "affiliationInfo": [
              {
                  "identifierInfo": [
                      {
                          "affiliationId": "https://ror.org/##",
                          "affiliationIdType": "ROR",
                          "identifierShowFlg": "true"
                      }
                  ],
                  "affiliationNameInfo": [
                      {
                          "affiliationName": "NII",
                          "affiliationNameLang": "en",
                          "affiliationNameShowFlg": "true"
                      }
                  ],
                  "affiliationPeriodInfo": [
                      {
                          "periodStart": "2025-01-27",
                          "periodEnd": "2025-03-21"
                      }
                  ]
              }
          ],
          "communityIds": ["community1"]
      }
  }
```
データ構造

|項目名|型|必須|説明| | --- | --- | --- | --- | |force_change|boolean|✕|著者名の変更をアイテムに反映するかどうか| |author|object|〇|変更情報を格納する。

空の辞書はエラーとする。|

emailInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |email|string|✕|-|著者のメールアドレス|

authorIdInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |idType|string|〇※|-|著者識別子種別。選択肢は画面と同様（例：weko、orcid）| |authorId|string|〇※|-|著者識別子| |authorIdShowFlg|boolean|✕|true|［著者DBから入力］機能で、外部著者IDを自動入力するかどうか。|

※ idTypeとauthorIdの片方のみが送られた場合はエラーにする

authorNameInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |language|string|△※|-|著者姓名の記述言語。選択肢は画面と同様| |firstName|string|△※|-|著者名| |familyName|string|△※|-|著者姓| |nameFormat|string|✕|"familyNmAndNm"※|著者名と著者姓の組み合わせ方| |nameShowFlg|boolean|✕|true|［著者DBから入力］機能で、氏名が自動入力されるかどうか。|

※ firstNameまたはfamilyNameが指定されたときはlanguageは必須とする ※ language、firstname、familyNameが送られてきた場合でnameFormatが指定されていない場合のみデフォルト値を適用する

identifierInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |affiliationIdType|string|△※|-|所属機関識別子種別。選択肢は画面と同様（例：ISNI、ROR）| |affiliationId|string|△※|-|所属機関識別子| |identifierShowFlg|boolean|✕|true||

※ affiliationIdTypeとaffiliationIdの片方のみが送られた場合はエラーにする

affiliationNameInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |affiliationName|string|△※|-|所属機関名| |affiliationNameLang|string|△※|-|所属機関の記述言語。選択肢は画面と同様| |affiliationNameShowFlg|boolean|✕|true||

※ affiliationNameとaffiliationNameLangの片方のみが送られた場合はエラーにする

affiliationPeriodInfo

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |periodStart|string|✕|-|所属開始日。入力形式はyyyy-MM-dd。| |periodEnd|string|✕|-|所属終了日。入力形式はyyyy-MM-dd。|

communityIds

|項目名|型|必須|デフォルト値|説明| | --- | --- | --- | --- | --- | |communityIds[n]|string|△※|-|著者を管理するコミュニティのID|

※ コミュニティ管理者の場合は管理対象のコミュニティが指定されていない場合エラーにする。

レスポンス

レスポンスコード

| コード | 説明 | | --- | --- | | 200 | 正常終了 | | 400 | リクエストに不備がある | | 401 | OAuth2認証失敗 | | 403 | 該当ユーザに必要なロールが付与されていない | | 404 | 指定された著者が存在しない | | 500 | 内部のエラー |

レスポンスボディ

サンプル

  {
      "message": "Author successfully updated.",
      "author":{
          "emailInfo": [
              {
                  "email": "sample@xxx.co.jp"
              }
          ],
          "authorIdInfo": [
              {
                  "idType": "ORCID",
                  "authorId":"https://orcid.org/##",
                  "authorIdShowFlg": "true"
              }
          ],
          "authorNameInfo": [
              {
                  "language": "en",
                  "firstName": "John",
                  "familyName": "Doe",
                  "nameFormat": "familyNmAndNm",
                  "nameShowFlg": "true"
              }
          ],
          "affiliationInfo": [
              {
                  "identifierInfo": [
                      {
                          "affiliationId": "https://ror.org/##",
                          "affiliationIdType": "ROR",
                          "identifierShowFlg": "true"
                      }
                  ],
                  "affiliationNameInfo": [
                      {
                          "affiliationName": "NII",
                          "affiliationNameLang": "en",
                          "affiliationNameShowFlg": "true"
                      }
                  ],
                  "affiliationPeriodInfo": [
                      {
                          "periodStart": "2025-01-27",
                          "periodEnd": "2025-03-21"
                      }
                  ]
              }
          ],
          "communityIds": ["community1"]
      }
  }

データ構造

|項目名|型|説明| | --- | --- | --- | |authors|object|変更情報を格納する。|

emailInfo

|項目名|型|説明| | --- | --- | --- | |email|string|著者のメールアドレス|

authorIdInfo

idtypeは文字列に変換して返す（例：weko、orcid）

|項目名|型|説明| | --- | --- | --- | |idType|string|著者識別子種別。選択肢は画面と同様| |authorId|string|著者識別子| |authorIdShowFlg|boolean|［著者DBから入力］機能で、外部著者IDを自動入力するかどうか。|

authorNameInfo

|項目名|型|説明| | --- | --- | --- | |language|string|著者姓名の記述言語。選択肢は画面と同様| |firstName|string|著者名| |familyName|string|著者姓| |nameFormat|string|著者名と著者姓の組み合わせ方| |nameShowFlg|boolean|［著者DBから入力］機能で、氏名が自動入力されるかどうか。|

identifierInfo
affiliationIdTypeは文字列に変換して返す（例：ISNI、ROR）

|項目名|型|説明| | --- | --- | --- | |affiliationIdType|string|所属機関識別子種別。選択肢は画面と同様| |affiliationId|string|所属機関識別子| |identifierShowFlg|boolean||

affiliationNameInfo

|項目名|型|説明| | --- | --- | --- | |affiliationName|string|所属機関名| |affiliationNameLang|string|所属機関の記述言語。選択肢は画面と同様| |affiliationNameShowFlg|boolean||

"affiliationPeriodInfo"

|項目名|型|説明| | --- | --- | --- | |periodStart|string|所属開始日。入力形式はyyyy-MM-dd。| |periodEnd|string|所属終了日。入力形式はyyyy-MM-dd。|

communityIds

|項目名|型|説明| | --- | --- | --- | |communityIds[n]|string|著者を管理するコミュニティのID|

7.3. 処理概要

ユーザー認証する
- リクエストに Authorization ヘッダーがある場合は、記載されたアクセストークンを使用しユーザーを認証する。認証に失敗した場合は401エラーを返す。
スコープを確認する
- 必要なスコープがついていなければ403エラーを返す。
ユーザーの権限を確認する
- スコープに設定されている権限が満たせていなければ403エラーを返す。
リクエストを確認する
- identifierが整数値でもUUIDでもない場合は400エラーにする。
- 必須の項目が送られていない場合は400エラーにする。
- authorが空だった場合は、400エラーとなりエラーメッセージ「author can not be null.」が返却される。
- 送られてきた値の型が定義と異なる場合は400エラーを返す。
- authorIdInfo.idtypeがWEKOの項目が存在しない場合は400エラーを返す。
指定された著者を確認する
- identifierで著者情報を検索する。
- 指定された著者情報が存在しない場合は404エラーを返す。
著者情報を確認する
- authorIdInfo.idType、authorNameInfo.language、affiliationInfo.identifierInfo.affiliationIdType、affiliationInfo.affiliationNameInfo.affiliationNameLangの値が選択肢に無い値の場合、400エラーを返す。
- authorIdInfoについて、idTypeとauthorIdの片方のみが送られた場合は400エラーを返す。
- authorNameInfoについて、firstNameまたはfamilyNameが指定されたとき、languageが指定されていなければ400エラーを返す。
- identifierInfoについて、affiliationIdTypeとaffiliationIdの片方のみが送られた場合は400エラーを返す。
- affiliationNameInfoについて、affiliationNameとaffiliationNameLangの片方のみが送られた場合は400エラーを返す。
- affiliationPeriodInfoについて、以下の場合400エラーを返す。
  - yyyy-MM-ddの入力形式を満たさない場合
  - 所属開始日（periodStart）が所属終了日（periodEnd）より後の日付の場合
- communityIdsについて、以下の場合400エラーを返す。
  - 許可されていない記号や制御文字が含まれる場合
  - DBに存在しないコミュニティIDが指定された場合
  - コミュニティ管理者権限のユーザーが、指定したIDの中に管理対象コミュニティを一つも含まない場合
  - コミュニティ管理者で、以下の場合403エラーを返す。
  - 管理対象外コミュニティのIDを新たに指定した場合
  - 変更前の著者に紐づいていた管理対象外コミュニティIDを指定しない場合
  - 管理対象コミュニティに紐づかない著者を変更対象に指定した場合
著者情報を変更する
- authorIdInfo.idType、affiliationInfo.identifierInfo.affiliationIdTypeは与えられた値で検索しIDを引っ張ってくる。
- DBとElasticsearchの著者情報を置きかえる。
- エラーが発生した場合は、ロールバックして500エラーを返す。
著者情報の更新をアイテムのメタデータに反映する
- pk_idでauthor_linkを検索し、著者名以外の著者情報の変更をアイテムのメタデータに反映する。
- force_changeがTrueの場合は、著者名の変更もアイテムのメタデータに反映する。
レスポンスを返す
- 変更した著者情報の内容をjson形式にエンコードしたものをレスポンスボディに入れ、レスポンスコード200を返す。
- idtypeとaffiliationIdTypeはidではなくschemeの文字列に変換して返す。

8. 著者DB著者削除

8.1. 機能内容

OAuth2認証機能を用いてユーザーの適切なアクセス制限を行う。
指定された著者情報を削除する。
スコープとロールによるアクセス制御を行う。

8.2. API仕様

関連モジュール

weko_authors.rest.py
weko_authors.scopes.py
weko_authors.config.py

エンドポイント

DELETE /api/{version}/authors/{identifier}

スコープ

author:delete

リクエスト

パスパラメータ

| 項目 | 説明 | | --- | --- | | version | APIのバージョン | | identifier | 削除対象の著者を一意に識別する値。

authorsテーブルのIDまたはElasticSearchのUUID のいずれかを指定する。 |
ヘッダーパラメータ

| 項目 | 値 | 必須 | 説明 | | --- | --- | --- | --- | | Authorization | Bearer | 〇 |操作するWEKOユーザーのOAuth認証情報。アクセストークンを用いる。|

レスポンス

レスポンスコード

| コード | 説明 | | --- | --- | | 200 | 正常終了 | | 400 | リクエストに不備がある | | 401 | OAuth2認証失敗 | | 403 | 該当ユーザに必要なロールが付与されていない | | 404 | 指定された著者が存在しない | | 500 | 内部のエラー |

8.3. 処理概要

ユーザー認証する
- リクエストに Authorization ヘッダーがある場合は、記載されたアクセストークンを使用しユーザーを認証する。認証に失敗した場合は401エラーを返す。
スコープを確認する
- 必要なスコープがついていなければ403エラーを返す。
ユーザーの権限を確認する
- スコープに設定されている権限が満たせていなければ403エラーを返す。
リクエストの確認
- identifierが整数値でもUUIDでもない場合は400エラーにする。
パラメータの確認
- identifierで著者情報を検索する。
- 指定された著者情報が存在しない場合は404エラーを返す。
- コミュニティ管理者の場合、削除対象の著者は管理対象コミュニティに関連付けられている必要がある。該当しない場合は403エラーを返す。
著者を削除する
- DBとElasticsearchの著者情報のis_deletedをTrueに書き変える。
- エラーが発生した場合は、ロールバックして500エラーを返す。

9. 更新履歴

日付	GitHubコミットID	更新内容
2025/2/17		初版作成
2025/5/30		REST対応
2025/11/27	-	WEKO ID対応

API-13: 著者DB機能API

著者DB機能API

目次

1. 目的

2. 要求仕様

3. エンドポイント一覧

4. スコープと利用可能なロールの関係

5. 著者DB検索

5.1. 機能内容

5.2. API仕様

リクエスト

レスポンス

5.3. 処理概要

6. 著者DB著者登録

6.1. 機能内容

6.2. API仕様

リクエスト

レスポンス

6.3. 処理概要

7. 著者DB著者変更

7.1. 機能内容

7.2. API仕様

リクエスト

レスポンス

7.3. 処理概要

8. 著者DB著者削除

8.1. 機能内容

8.2. API仕様

リクエスト

レスポンス

8.3. 処理概要

9. 更新履歴

results matching ""

No results matching ""