2. ePIC での PIDINST 用ハンドル識別子

ePIC での PID ハンドルレコードに用いられている、 PIDINST メタデータスキーマのプロパティ、サブプロパティ、属性は以下より参照できます。 ‘objects’ の前に ‘#’ を配置することで、対人可読な形式とJSON表現を相互に変換することができます。それぞれのプロパティ、サブプロパティ、属性は、固有のハンドルレコードを通じて解決することができます。

対人可読形式	http://dtr-test.pidconsortium.eu/#objects/21.T11148/17ce618137e697852ea6
JSONでの表現	http://dtr-test.pidconsortium.eu/objects/21.T11148/17ce618137e697852ea6

2.1. 新しい装置PIDの生成

ePICハンドルは、HTTPアプリケーションプロトコルを使用したRESTfulなWebサービス経由でアクセスし管理されます。このサービスまたはアプリケーションプログラミングインタフェース(API)は、主要な交換フォーマットとしてJSONを使用します。独自のビジネスロジックと追加サービスに合わせて、一般的でより基本的なハンドルAPIや、使用するPIDサービスに実装されているならば、ePIC APIを適用することができます。以下の例では、PIDINSTハンドルをePIC APIのテスト環境で、将来的に本番環境に移行することを視野に入れて、ePIC API経由で作成します。また、最後にePIC APIまたはHandle APIのいずれかを使用したPIDの基本的なCRUD操作の概要を示します。

新しいPIDを生成して装置に割り当てるには、ePICのメンバー（プロバイダ）になるか、現在のメンバーまたは独自のePIC APIエンドポイントを持つリポジトリのいずれかと連携する必要があります。テスト環境を使用してPIDを作成するには、テスト環境のプレフィックス21.T11998を使用する承認を得るための認証情報(ユーザー名とパスワード)を取得する必要があります。これらは、support@pidconsortium.net にメールを送ることで ePIC より取得できます。

PIDは通常、POST/PUTメソッドを使用して作成されます。 POSTメソッドを使用すると、ハンドルレコードのサフィックスにUniversally Unique Identifier (UUID)が自動的に生成されます。または、ローカル識別子を使ってPUTメソッドでサフィックスを手動で作成することもできます(https://doc.pidconsortium.eu/guides/api-create/ を参照)。

以下のすべての例は、コマンドライン(Linuxの場合)でcURLリクエストを使用しています。PHP、Perl、Python でのリクエストも可能です (https://doc.pidconsortium.eu/guides/api-create/ を参照)。また、例ではテスト用のAPIエンドポイント http://vm04.pid.gwdg.de:8081/handles/ を使用しています。 ePICの各メンバーは、独自のAPIエンドポイントを使用することになります。

自動生成されるUUIDをサフィックスとしてPIDハンドルレコードを生成する場合:

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X POST --data '[{"type":"URL","parsed_data":"https://linkedsystems.uk/system/instance/TOOL0022_2490/current/"}]' http://vm04.pid.gwdg.de:8081/handles/21.T11998/

実行結果: https://vm04.pid.gwdg.de:8081/handles/21.T11998/0000-001A-64A4-A

自動生成されるUUIDをサフィックスに埋め込み、PIDハンドルレコードを生成する場合:

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X POST --data '[{"type":"URL","parsed_data":"https://linkedsystems.uk/system/instance/TOOL0022_2490/current/"}]' http://vm04.pid.gwdg.de:8081/handles/21.T11998/\?prefix=BODC\&suffix=TEST

実行結果: https://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

PUTメソッドを用い、手動でサフィックスを生成する場合:

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X PUT --data '[{"type":"URL","parsed_data":"https://linkedsystems.uk/system/instance/TOOL0022_2490/current/"}]' http://vm04.pid.gwdg.de:8081/handles/21.T11998/564987-8865544-9998

実行結果: https://vm04.pid.gwdg.de:8081/handles/21.T11998/564987-8865544-9998

2.2. PIDハンドルレコードを参照する

ハンドルレコードにおいて URL が設定されている場合、ハンドルレコードを参照すると、設定されたURLにリダイレクトされます:

http://hdl.handle.net/21.T11998/0000-001A-3905-F

ハンドルレコードを直接参照したい場合:

http://hdl.handle.net/21.T11998/0000-001A-3905-F?noredirect

REST APIコールにより、JSON形式を取得できます:

http://hdl.handle.net/api/handles/21.T11998/0000-001A-3905-F

2.3. PIDハンドルレコードの内容更新

プロパティはPUTメソッドを用い、cURLリクエストで直接JSONプロパティを指定するか、JSONファイルを介してパースすることにより更新できます。(JSON のサンプル も参照）。

cURL request で直接プロパティを指定する場合:

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X PUT --data '[{"type": "21.T11148/8eb858ee0b12e8e463a5","parsed_data": "{\"identifierValue\":\"http://hdl.handle.net/21.T11998/BODC-0000-001A-64A3-B-TEST\",\"identiferType\":\"MeasuringInstrument\"}"},{"type": "21.T11148/4eaec4bc0f1df68ab2a7","parsed_data": "[{\"Owner\": {\"ownerName\":\"National Oceanography Centre\",\"ownerContact\":\"louise.darroch@bodc.ac.uk\",\"ownerIdentifier\":{\"ownerIdentifierValue\":\"http://vocab.nerc.ac.uk/collection/B75/current/ORG00009/\",\"ownerIdentifierType\":\"URL\"}}}]"}]' http://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

補足: JSON parsed_data string 内においては、ダブルクォーテーションをバックススラッシュ(\)でエスケープする必要があります。

JSONファイルでプロパティを指定する場合:

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X PUT --data @/users/.../ePIC_json_example.json http://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

2.4. PIDの管理

2.4.1. ePIC API を使用する場合

以下のHTTPメソッドにより、ユーザ名-パスワードに基づいたePIC APIを使用して、ユーザのPIDハンドルレコードを管理することができます。サーバ: vm04.pid.gwdg.de, ポート: 8081, リソース: handles/ としています。

PID の取得

curl -D- -u "username:password" -X GET -H "Content-Type: application/json" http://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

PID の削除 (本運用のハンドルに対しては許可されません)

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X DELETE http://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

PID の更新

curl -v -u "username:password" -H "Accept:application/json" -H "Content-Type:application/json" -X PUT --data '[{"type":"21.T11148/8eb858ee0b12e8e463a5","parsed_data":"{\"identifierValue\":\"http://hdl.handle.net/21.T11998/BODC-0000-001A-64A3-B-TEST\",\"identiferType\":\"MeasuringInstrument\"}"}]' http://vm04.pid.gwdg.de:8081/handles/21.T11998/BODC-0000-001A-64A3-B-TEST

2.4.2. Handle API を使用する場合

以下のHTTPメソッドにより、ユーザーは証明書に基づく汎用ハンドルAPIを使用して、PIDハンドルレコードを管理することができます。サーバ: vm04.pid.gwdg.de, ポート: 8081, リソース: haneles/ としています。

privkey.pem and certificate_only.pem を取得する手順は、例えば http://eudat-b2safe.github.io/B2HANDLE/creatingclientcertificates.html に記載されています。

Handle API には内部でのサフィックス生成機能がありません。サフィックスは、ユーザが提供する必要があります。

Handle API は、POST, GET, DELETE メソッドのみが利用できます。これはすなわち、クレデンシャルが十分であれば、意図せず発行した新規作成のリクエストにより、既存のPIDが上書きされる可能性があります。利用者は事前にPIDの重複がないことを検知する必要があります。

アクセスパラメータ:

ユーザ名(USER)、公開鍵(HS_PUBKEY)のインデックス(INDEX)、証明書ファイルのプレフィックス(PREFIX)が、${INDEX}_${PREFIX}_${USER}_???.pem という命名規則で保存されているとします。

PATH="/SomePath2Certs"
PREFIX="21.T11998" # prefix of the PID service
USER="USER21" # USER that has access to PIDs under $PREFIX
INDEX="300"  # index where HS_PUBKEY is stored for $USER
SERVPORT="vm04.pid.gwdg.de:8001" # PID service and port
VERBOSE="" # optional “ -v "
# Certificates
USERKEY="${PATH}/Certificates/${INDEX}_${PREFIX}_${USER}_privkey.pem"
USERCERT="${PATH}/Certificates/${INDEX}_${PREFIX}_${USER}_certificate_only.pem"

ハンドルの生成

curl -s --insecure ${VERBOSE} --key ${USERKEY} --cert ${USERCERT} -H "Content-Type:application/json" -H 'Authorization: Handle clientCert="true"' -X PUT --data  '{"values":[{"index":100,"type":"HS_ADMIN","data":{"value":{"index":'${INDEX}',"handle":"'${PREFIX}'\/'${USER}'","permissions":"011111110011","format":"admin"},"format":"admin"}},{"index":1,"type":"URL","data":"www.gwdg.de"}]}' https://${SERVPORT}/api/handles/${PREFIX}/test_epic3_1234

生成したハンドルの取得

curl -s --insecure ${VERBOSE} --key ${USERKEY} --cert ${USERCERT} -H "Content-Type:application/json" -H 'Authorization: Handle clientCert="true"' -q https://${SERVPORT}/api/handles/test_epic3_1234

生成したハンドルの修正

curl -s --insecure ${VERBOSE} --key ${USERKEY} --cert ${USERCERT} -H "Content-Type:application/json" -H 'Authorization: Handle clientCert="true"' -X PUT --data  '{"values":[{"index":100,"type":"HS_ADMIN","data":{"value":{"index":'${INDEX}',"handle":"'${PREFIX}'\/'${USER}'","permissions":"011111110011","format":"admin"},"format":"admin"}},{"index":1,"type":"URL","data":"pid.gwdg.de"}]}' https://${SERVPORT}/api/handles/${PREFIX}/test_epic3_1234

生成したハンドルの削除

curl -s --insecure ${VERBOSE} --key ${USERKEY} --cert ${USERCERT} -H "Content-Type:application/json" -H 'Authorization: Handle clientCert="true"' -X DELETE  https://${SERVPORT}/api/handles/test_epic3_1234

2. ePIC での PIDINST 用 ハンドル識別子