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リリース23.2.1からは、Spatial Studio UIにログインすることなく、プログラムでアクセス・トークンを作成できます。これにより、アクセス・トークンの管理と配布がより適切で安全になります。こうしたトークンは、アプリケーションが必要としたときに、短期使用のためにのみ作成されるためです。

プログラムでアクセス・トークンを作成するには、まず、アプリケーションにアクセスジェネレータ・トークンが必要です。これは、Spatial Studioユーザーごとにシステムによって自動作成される永続トークンです。このトークンの目的は、Studioの広範なREST APIセットとの対話に使用できる、通常の(ただし、存続期間が短い)アクセス・トークンを作成することです。アクセスジェネレータ・トークン自体を使用して、StudioのREST APIを呼び出すことはできません(通常のトークンを作成するものを除く)。

アクセスジェネレータ・トークンを取得するには、「アクセスジェネレータ・トークンのコピー」を参照してください。

アクセスジェネレータ・トークンは、有効なSpatial Studioユーザーに永続的に関連付けられるため、次の事項を確認してください:

  • トークンは常にセキュアな状態を維持すること。たとえば、WebページのJavaScriptコードでトークンを公開しないでください。
  • 一般的なワークフローでは、アプリケーションのバックエンドでアクセスジェネレータ・トークンを格納して使用すること。また、ユーザー・セッションごとに、Spatial Studioサーバーと必要に応じて対話するために、JavaScriptコードで使用できる通常のアクセス・トークンを作成してください。

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