API に対する認証¶
Mapray Cloud API へのアクセスには API Key またはアクセストークンによる認証が必要になります。
このページでは API Key とアクセストークンの作成と利用方法を説明します。
API Key¶
API Key を利用するためには、まず Mapray Cloud の UI 上から API Key の作成を行います。作成方法は「API Key」を参照してください。
作成した API Key は、Mapray Cloud API への HTTP リクエスト時に、X-API-Key ヘッダで送信することで認証することができます。
curl --request GET \
--url "https://api.mapray.com/pcdatasets/v2" \
--header "X-API-Key: 作成したAPI Key"
API Key は組織に紐づいたものであるため、組織のリソースにアクセスすることはできますが、ユーザーのリソースにアクセスすることはできません。ユーザーのリソースにアクセスする場合は後述する User Token を使用してください。
また、API Key ではアクセス可能なリソースの制御ができないため、対象の組織のリソース全てにアクセスできてしまいます。より細かいアクセス制御を行いたい場合は、アクセストークンの利用をご検討ください。
アクセストークン¶
アクセストークンを利用すると、API Key よりも細かくリソースへのアクセス制御を行うことができます。これにより、データセットの取得のみが可能なアクセストークンや、組織のメンバー管理のみを行うためのアクセストークンといった特定の用途に限定したトークンを作成することができるようになっています。 また、アクセストークの有効期限を設定することができるようになっているため、よりセキュアなトークンの運用が可能です。
アクセストークンには User Token と Organization Token の 2 種類があり、それぞれユーザーに紐づくリソースと組織に紐づくリソースへアクセスするために利用します。
User Token¶
User Token を利用すると、ユーザーに紐づいたリソースにアクセスすることが可能になります。具体的には、ユーザー自身の情報と所属する組織の情報の取得、新たな組織の作成などを行うことが可能です。
User Token の作成方法とスコープについては、「User Token 」をご参照ください。
作成した User Token はAuthorizationヘッダで送信することで認証することができます。
curl --request GET \
--url "https://api.mapray.com/organization/v2" \
--header "Authorization: Bearer 作成したUser Token"
Organization Token¶
Organization Token を利用すると、組織に紐づいたリソースにアクセスすることが可能になります。具体的には、データセットの作成・取得や組織のメンバー管理などを行うことが可能です。
Organization Token の作成方法とスコープについては、「Organization Token 」をご参照ください。
作成した Organization Token はAuthorizationヘッダで送信することで認証することができます。
curl --request GET \
--url "https://api.mapray.com/pcdatasets/v2" \
--header "Authorization: Bearer 作成したOrganization Token"
API によるアクセストークンの管理¶
User Token と Organization Token のスコープには、Token Read/Create/Update/Delete というものがあります。
これらのスコープを付与すると、User/Organization Token を使ってアクセストークンを操作することができるようになります。
これを利用すると、例えば Organization Token を管理するための専用の Organization Token を一つ作成し、データセットへのアクセスなどは管理用トークンを使って有効期限付きの Organization Token を都度作成して使用する、といった運用をすることが可能となっています。
各トークンを操作するための API については以下のリファレンスご参照ください。