build-with-arcgis-and-openlayers

OpenLayers と ArcGIS を使用した開発

OpenLayers（OL）は、ArcGIS サービスを使用してブラウザーのマップを描画します。ol（マップ／レイヤー）、ol-mapbox-style（ArcGIS Basemap Styles v2）、ArcGIS REST JS（@esri/arcgis-rest-*。認証、クエリ、ロケーションサービス）を使用します。

OpenLayers は ArcGIS Maps SDK ではありません。FeatureLayer／WebMap クラスはなく、ArcGIS のポップアップテンプレートやレンダラーも解釈しません。エンドポイントを解決し、ArcGIS JSON を明示的に変換してください。

ArcGIS アカウントの要件

開発者がアプリケーションを作成するには、次のいずれかの ArcGIS アカウントが必要です。ArcGIS Location Platform（無料）、または Creator、Professional、Professional Plus のユーザータイプを持つ ArcGIS Online または ArcGIS Enterprise のアカウントです。アカウントのユーザータイプ、ロール、権限によって、利用できるリソースや操作が異なります。

認証

必ず確認してください：さまざまな対象者、ユースケース、アプリケーションの種類に適した認証方式など、ArcGIS 認証の要件については、follow-arcgis-authentication-patterns スキルを参照してください。スキルが利用できない場合は、プロジェクトに既存の認証パターンがないか検索してください。見つからない場合は、ドキュメント MCP に認証のベストプラクティスを問い合わせてください。

インストールとセットアップ

ベクターベースマップには ol-mapbox-style を使用し、ジオコーディング、ルーティング、標高、ジオエンリッチメント、認証などのロケーションサービスには REST JS を使用してください。OpenLayers の CSS を読み込み、マップコンテナーに 0 ではない明確な幅と高さを設定し、file:// ではなく HTTP(S) で配信し、現在の API とバージョンを確認してください。

新しいアプリケーション

プロンプト／プロジェクトから要件を推測し、スキャフォールディングの前に不明点を確認してください。

CDN を使用した新しいアプリケーション

最新の ArcGIS OpenLayers examples を使用してください。ol.css をスタイルシートとしてリンクし、dist/ol.js と必要な REST JS UMD スクリプトを依存関係の順に読み込みます。これらのバンドルはグローバルを公開するため、ESM として読み込まないでください。MCP を使って URL／バージョンを確認してください。ArcGIS のドキュメントでは CDN インポートが多く使われています。テスト、デモ、チュートリアル、サンプル、軽量なクイックスタートでは CDN を使用してください。

npm を使用した新しいアプリケーション

フレームワークが指定されていない場合は、npm create ol-app my-app または Vite を使用してください。ol、ol-mapbox-style、および必要な @esri/arcgis-rest-* パッケージ（request、feature-service、geocoding、routing、places）をインストールしてください。ESM インポートを使用し、バンドラー経由で ol/ol.css をインポートしてください。ol-mapbox-style の注意事項に従って、互換性のあるバージョンを固定してください。本番環境、大規模なアプリ、またはフレームワークを使うアプリでは、こちらを優先してください。プロジェクトのパッケージマネージャーを使用してください。React、Angular、Vue、Svelte がサポート対象のフレームワークです。create ol-app 以外のフレームワーク固有テンプレートを使う場合は、ユーザーのリクエストに関係のないテンプレートファイル（例：counter.js）をすべて削除してください。

既存のアプリケーション

インストールする前に、パッケージマネージャー／ロックファイル、フレームワーク、CDN とモジュールのどちらを使用しているか、TypeScript／ESLint の設定、バンドラーを確認してください。既存の構成に合わせ、必要な ol、ol-mapbox-style、REST JS のパッケージだけを追加してください。認証情報／環境変数の規則を維持し、ol/ol.css をインポートしてマップのサイズを設定し、アップグレード前に互換性を確認してください。

ドキュメントの検索方法

Esri 開発者向けドキュメントサーバーの MCP を使用して、ドキュメントを検索できます：

https://developers-mcp.arcgis.com/mcp

search_esri_developer_docs ツールを使用して、focus_area パラメーターに openlayers を指定し、search_term も指定すると、信頼できるドキュメントページを検索できます。ArcGIS REST JS の検索では、arcgis-rest-js の focus area を使用してください。fetch_esri_developer_docs ツールでは、page_url パラメーターを指定すると、ドキュメントページ全体を Markdown 形式で取得できます。

公式ドキュメントに基づかない推奨事項や前提条件は、明確に示してください。MCP を利用できない場合は、以下の公式ドキュメント URL を参照してください。

ドキュメントへのリンク

• ArcGIS OpenLayers
• OpenLayers API
• ol-mapbox-style
• REST JS
• 帰属表示

パターンとガイドライン

認証の統合

• サービスごとのアカウント対応を確認してください。Enterprise の認証情報だけでは ArcGIS Location Services の認可を受けられません。これらのサービスには、対応する Location Platform/Online の認証情報を使用してください。
• API キー：@esri/arcgis-rest-request の ApiKeyManager.fromKey(apiKey) を、REST JS の authentication として使用してください。最小限の権限とアイテムへのアクセスを付与し、ブラウザー用キーはリファラーで制限してください。ブラウザー用キーは、ビルド時の環境変数で設定した場合でも外部から確認できます。クライアントシークレットは絶対に公開しないでください。
• OAuth：REST JS の ArcGISIdentityManager を、PKCE と正確なリダイレクト URI とともに使用してください。
• ネイティブ OL ソース：REST JS は直接統合されません。ソースローダーまたは tileLoadFunction で認証情報を付与・更新してください。クライアントシークレットを公開したり、トークンを含む URL をログに記録したりしないでください。
• arcgis-rest-js と follow-esri-authentication-patterns のスキルを参照してください。

ベースマップ、スタイル、帰属表示

• Basemap Styles v2 を適用するには、ol-mapbox-style の apply(layerGroup, styleUrl) を専用の LayerGroup に使用し、その後でマップに追加してください。
• 依存レイヤーを追加する前にスタイルの適用が完了するのを待ち、失敗を処理してください。スタイルを切り替える際は、このグループのみを置き換えてください。
• 表示される Powered by Esri と、各データアイテムで必要な帰属表示・謝辞を維持してください。ソースのクレジットを上書きしないでください。

レイヤーとソースの選択

• フィーチャサービス：REST JS を使用してレイヤーのエンドポイント（FeatureServer/<layerId>）にクエリを送信してください。EsriJSON／GeoJSON で解析して VectorSource に追加します。読み込みオプションの dataProjection には応答の CRS を、featureProjection にはビューの CRS を設定してください。ビューポートの読み込みには ol/loadingstrategy.js の bbox を使用し、重複を避けるため、サービスのオブジェクト ID から安定したフィーチャ ID を割り当ててください。ローダーが失敗した場合、removeLoadedExtent(extent) を呼び出すと再読み込みが可能になりますが、自動では再読み込みされません。再試行回数に上限を設けたうえで、後続の読み込みサイクルまたは意図的なトリガーで再試行してください。
• フィーチャのスタイリング：レイヤーのメタデータ（drawingInfo.renderer）を確認し、関連するシンボル、個別値／クラス区分のルール、縮尺制限を OpenLayers のスタイルに反映してください。凡例と描画されたシンボルを一致させてください。対応していないレンダラーの詳細がある場合は、忠実に再現できたと主張せず、その内容を報告してください。
• 編集：機能と権限を確認してください。OpenLayers のフィーチャーオブジェクトではなく、ArcGIS のジオメトリ／属性を REST JS の applyEdits に送信してください。追加・更新・削除の各結果を確認してください。リクエストが解決されても、編集が失敗している場合があります。成功した編集のみを更新・再読み込みし、失敗を明示してください。
• ベクタータイル：大規模なデータやヒット検出には、VectorTileLayer と VectorTileSource（ol/format/MVT）を使用してください。公開済みのスタイルにはサービスのスタイル JSON と ol-mapbox-style を使用し、意図的にスタイルを上書きする場合は明示的な OpenLayers スタイルを使用してください。属性はタイルやズームレベルによって異なるため、すべてのデータを対象とするクエリや編集にはフィーチャサービスを使用してください。
• キャッシュ済みタイル：/MapServer/tile/{z}/{y}/{x} には TileLayer と XYZ を使用してください。標準の XYZ グリッドを前提とする前に、tileInfo とサービスの空間参照を確認し、タイルサイズ、原点、解像度、レベル ID を検証してください。必要に応じて、一致するタイルグリッドとレベルマッピングを設定してください。キャンバスのエクスポートには crossOrigin: "anonymous" を設定し、サービスの CORS を確認してください。このオプションを設定するだけでは不十分です。
• ダイナミックマップサービス：エクスポートされた MapServer 画像には、ImageLayer と ImageArcGISRest、または TileLayer と TileArcGISRest を使用してください。
• ポップアップ：属性は信頼できないものとして扱ってください。DOM の textContent を優先し、HTML を使用する場合はサニタイズしてください。

座標系とジオメトリの処理

• OpenLayers のデフォルトのビュー投影法は Web Mercator（EPSG:3857）です。ArcGIS の位置情報サービスの例では、WGS 84（EPSG:4326）の座標を [longitude, latitude] の順序で使用するものが多いですが、サポートされる入力および出力の空間参照は、サービスや操作によって異なります。サービスの要件を確認し、地理座標とマップのビュー投影法を変換する場合は fromLonLat / toLonLat を使用してください。デフォルト以外のビューでは、必要に応じて未サポートの投影法を登録し、fromLonLat/toLonLat および ol/sphere の計測に実際のビュー投影法を渡してください。
• クエリの inSR には入力ジオメトリの空間参照を、outSR には要求する出力 CRS を設定してください。Web Mercator 以外のビューでは、3857 をハードコードしないでください。
• レスポンス形式（EsriJSON/GeoJSON）を一致させ、リーダーの dataProjection と featureProjection を設定してください。
• 実世界の距離や面積の計測には ol/sphere を使用してください。Web Mercator の平面計測では歪みが生じ、特に高緯度で顕著になります。

クエリ、ページネーション、パフォーマンス

• ?f=pjson で maxRecordCount と機能を確認してください。
• exceededTransferLimit の場合、サポートされていれば安定した並べ替えを指定して resultOffset/resultRecordCount を使用してください。それ以外の場合は、オブジェクト ID を取得してバッチ単位でクエリしてください。クエリのドキュメントを参照してください。
• 必要な outFields をリクエストし、属性のみのクエリでは returnGeometry: false を設定してください。
• 大規模なデータセットでは、リクエストの同時実行数を制限し、適切なズームレベルでクエリしてください。bbox ローディングでは、ユーザーがパンしてもフィーチャーが保持されます。上限付きのキャッシュか、ビューポートの置き換えを選択してください。エリアを再訪したときに欠落データが再読み込みされるよう、読み込み済みエクステントの管理とフィーチャーの削除を整合させてください。
• where 句は、既知のフィールドと検証・エスケープ済みの値から構築し、生のユーザー入力は決して使用しないでください。
• forEachFeatureAtPixel の layerFilter で、ポップアップのヒットテスト対象を制限してください。
• ジオコーディングはデバウンスし、古い結果を防止してください。読み込み中、空、エラーの各状態を表示し、失敗を空のデータとして扱わないでください。

フレームワークのライフサイクルと堅牢性

• React/Vue/Angular では、DOM のマウント後にライフサイクルフック（useEffect、onMounted、ngAfterViewInit）で初期化してください。マップはリアクティブな状態ではなく、ref/service に保持してください。
• アンマウント時には、リスナーを unByKey で解除し、コントロールとオーバーレイを削除し、保留中の処理やオブザーバーをキャンセルして、map.setTarget(undefined) を呼び出し、マップを切り離してください。破棄後に届いた非同期結果は無視してください。
• コンテナーのサイズが変更されたとき、または表示状態になったときに map.updateSize() を呼び出してください。
• 拒否されたリクエストとソースの読み込みエラー（tileloaderror、imageloaderror、featuresloaderror）を処理し、トークンを漏らさず、ユーザーが対処できるエラーを表示してください。
• ラベル付きコントロール、キーボード操作、アクセシブルなステータスメッセージ、タッチしやすいレイアウトを必須とし、重要な結果には代替となるリストまたはテーブルを用意してください。
• マップコンテナーに明確な高さを設定し、描画されたビューポートがゼロサイズでないことを確認してください。

検証プロセス

• 互換性のあるパッケージをインストールしてビルドできる。
• CSS とコンテナーの寸法が設定され、レイアウトが崩れずにマップが描画される。
• ブラウザーコードにクライアントシークレットを含めずに認証が成功する。
• ベースマップとレイヤーが、必要な Esri およびデータのクレジット表記とともに描画される。
• フィーチャーのスタイルと凡例が意図したレンダラーのルールに一致し、未サポートの詳細が記録されている。
• クエリで正しい inSR/outSR を使用し、必要なデータを要求し、制限に対応して正しく描画する。
• パンを繰り返してもリクエストとフィーチャーの数が上限内に保たれ、削除されたエリアが再読み込みされ、失敗した読み込みを再試行できる。
• 操作で、空またはエラーの結果、部分的な編集失敗、古いレスポンスを安全でない HTML や未処理の拒否なしに処理する。
• 破棄時にリスナーを削除し、マップを切り離し、updateSize() を処理する。
• コントロールと結果がキーボードおよびタッチで操作でき、ステータスメッセージがアクセシブルで、レイアウトが小さな画面に適応する。
• ブラウザーのスモークテストで、描画、サービスリクエスト、操作、サイズ変更、破棄を確認し、コンソールとネットワークのエラーを確認する。ブラウザーテストができない場合は、未検証の項目を報告する。