1. ガイド
  2. Oracle Spatial StudioにおけるREST API

4 Oracle Spatial StudioにおけるREST API

Oracle Spatial Studioには、Webアプリケーション・ユーザー・インタフェース(UI)からのみでなく、コマンドラインからも、他のサーバーまたはWebアプリケーションからプログラムによってもアクセスできる豊富なRESTful APIが用意されています。

概要

Spatial Studio Webアプリケーションにログインすると、アプリケーションUIはREST APIエンドポイントを使用してアプリケーション・データを常に送受信します。エンドポイントにアクセスするためのURLは通常、<studio-base-URL>/api/v1で始まります。ベースURLは、https://localhost:4040/spatialstudioなどのSpatial Studioへのエントリ・ポイントです。Spatial Studio Webアプリケーションに初めてログインすると、ブラウザは複数のAJAXリクエストを送信してサーバーから様々なメタデータをロードします。REST APIエンドポイントは、アクセス権がある既存のプロジェクトのリスト、各種プリファレンスの設定、実行中のタスクのリストなど、様々なアクションを実行すると、Webアプリケーションによって常に使用されます。

たとえば、現在ログインしているユーザーの詳細情報を取得するために、WebアプリケーションはHTTP GETリクエストをURL: https://localhost:4040/spatialstudio/api/v1/userに送信します。これは、ベースURLがhttps://localhost:4040/spatialstudioであることを前提としています。このようなリクエストへのレスポンスは通常JSON形式ですが、圧縮ベクター・タイル(マップにジオメトリ・データセットを表示する場合)、イメージ(GeoRasterデータセットを表示する場合)など、他のタイプのデータを返すリクエストが他にもあります。

すべてのRESTエンドポイントのOpenAPI 3.0仕様は、付録AでYAML仕様の形式で入手できます。ただし、多くのリクエストには、(場合によっては非常に複雑な) JSONペイロードが必要です。これは、現在、自動生成されたOpenAPI YAML仕様の一部ではありません。これは、Spatial Studioの今後のリリースに記載される予定です。最も一般的なユースケースのJSONリクエスト・ペイロードの詳細は、この章のサブ項に記載されています。

アクセス・トークンについて

Spatial Studio UIとは別に、cURLなどのツールを使用してコマンドラインから、またはプログラムで外部アプリケーションから、ほとんどすべてのREST APIエンドポイントにアクセスすることもできます。どちらの場合も、トークンをサーバーに示す必要があるため、まずSpatial Studioからアクセス・トークンを取得する必要があります。また、アクセス・トークンを介してRESTエンドポイントにアクセスする場合、URLは常にパターン<studio-base-URL>/oauth/v1で始まります。URLでの唯一の違いは、パス・セグメントapiがoauthに置き換えられることです。Spatial Studio UI、外部ツールまたはその他のアプリケーションからのREST APIエンドポイントとの他のすべてのやり取りする動作は同じままです。

アクセス・トークンには、常にトークンを生成したSpatial Studioユーザーの一意のアイデンティティが含まれます。このユーザーはトークンの所有者とみなされます。所有者アイデンティティは、トークンを介してRESTエンドポイントにアクセスするときに常に検証されます。Spatial Studioで生成できる様々なタイプのアクセス・トークンの詳細は、「アクセス・トークンの生成」を参照してください。

次の各サブ項の例はすべて、適切なタイプのアクセス・トークンを取得していることを前提としています。要件を満たす最小特権アクセス・トークンを取得することをお薦めします。たとえば、状態変更操作(分析データセットの削除など)を呼び出す必要がない場合は、READ ONLYトークンで十分です。同様に、別のマッピング・アプリケーションでデータセットを消費および表示することのみが要件である場合は、サーバーから他の情報を問い合せるために使用することができないストリーミング専用アクセス・トークンの使用を検討してください。

また、次の各項の例では、Spatial Studioサーバーが稼働中で、URL https://localhost:4040/spatialstudioからアクセスできることを前提としています。