js-sdk

ArcGIS Maps SDK for JavaScript

まずターゲットを確認する

アプリのターゲットが ArcGIS Online なのか、特定の ArcGIS Enterprise バージョンなのかを確認してから、「最新」と決めつけずに、Esri の最新のバージョンマトリックス — https://developers.arcgis.com/javascript/latest/version-matrix/ — で SDK のバージョンを確認します。Enterprise のリリースによって SDK のバージョンが固定され、それに伴い Calcite のバージョンも固定されます。

世代ごとの境界を把握する

これらは通常のバージョンアップではありません。以下に示す世代は、別個の製品として扱ってください。

• 3.x — 2024-07-01 にサポート終了。移行先としては対象外です。
• 4.x — 3.x を全面的に書き直したものであり、単なるバージョンアップではありません。3.x → 4.x への移行は書き直しです。
• 5.x — セマンティックバージョニングに従い、4.x の開発を継続するものです。マイナーバージョンの更新には後方互換性がありますが、メジャーバージョンの更新には破壊的変更が含まれます。
• 3.x → 5.x への移行はアップグレードではなく、書き直しです。

ES モジュールまたはコンポーネントを使う — AMD は終了しています

arcgis-js-api AMD npm パッケージの最終リリースは 4.31 です。AMD の TypeScript 宣言と @arcgis/cli はサポート終了となっています。@arcgis/core の ES モジュールまたはコンポーネントパッケージを使ってビルドしてください。AMD でのスキャフォールディングは行わないでください。

ウィジェットよりコンポーネントを優先する

推奨される方法はコンポーネントの使用です。ウィジェットを使う場合、または MapView／SceneView をプログラムで初期化する場合は、コア API の CSS スタイルシートを手動で含める必要があります。これを省略すると、ビューが正しく表示されません。

Calcite のバージョンを固定する

Calcite は、対象の SDK で使用されるバージョン（上記のバージョンマトリックスを参照）または互換性のある、より新しいマイナーバージョンに固定します。

開発サーバーを選ぶ前にリダイレクト URL を確定する

ローカルでのサインインは、コード上の理由よりも環境上の理由で失敗することのほうがはるかに多く、開発サーバーは後から変更するのが最も難しい要素です。リダイレクト URL は OAuth 認証情報アイテムに保存された許可リストです。登録済みの値だけが有効であり、スキーム、ポート、パスは保証されません。まず許可される値を確定し、その値を配信できるサーバーを選んでください。

• 認証情報アイテムを自分で管理している場合 — アイテムのページで Settings > Application > Redirect URLs を開き、配信に使う URL を登録して、その URL を正確に配信します。

• 別の人が管理している場合（共有の client_id またはトレーニング用の client_id）— 組織の外部から登録内容を確認することはできませんが、検証はできます。候補ごとに認証エンドポイントへ一度リクエストします。400 は拒否、200 は許可を意味します。認証情報は不要です。

  https://www.arcgis.com/sharing/oauth2/authorize
    ?client_id=<APP_ID>&response_type=code&redirect_uri=<CANDIDATE>
  

  配信に使う予定のスキーム、正確なポート、パスの組み合わせをすべて検証してください。多くの組織では https://localhost だけを登録しているため、http:// 形式はすべて拒否され、127.0.0.1 を使う形式もすべて拒否されます。さらに、通常の HTTP 開発サーバー（VS Code Live Preview、http-server、python -m http.server）に後から TLS を追加することはできません。https だけが許可されている場合は、HTTPS で配信してください。ビルド手順のない CDN ベースのアプリなら、Vite と @vitejs/plugin-basic-ssl で十分です。また、自己署名証明書の警告を一度クリックして進む必要があることを、ユーザーに事前に伝えてください。伝えないと、失敗したように見えてしまいます。

リダイレクトは、トップレベルのブラウジングコンテキストで実行してください。ArcGIS はサインインページをフレーム内に表示しないため、VS Code Simple Browser などのプレビューパネルでは、サインインボタンを押しても何も起きません。window.top !== window.self を検出し、通常のタブで開くようユーザーに伝えてください。

API キーとユーザー認証の両方が設定されている場合は、API キーが優先されます。サインインに成功したにもかかわらず、匿名セッションのように動作する場合は、フローの不具合ではなく、不要な API キーが残っていることが通常の原因です。

ユーザー操作時にのみ認証情報を破棄する

セッションがない状態では、IdentityManager.checkSignInStatus() は毎回の読み込みで拒否されます。これには、ArcGIS が認証コードとともにリダイレクトして戻った直後の読み込みも含まれます。この拒否は通常の状態であり、エラーではないため、ハンドラーではサインアウト状態の UI を表示するだけにしてください。そこで destroyCredentials() を呼び出すと、戻りの遷移に必要な PKCE の状態（sessionStorage、キー esriJSAPIOAuth、ページパスで名前空間化）を削除してしまいます。その結果、ユーザーはサインインに成功しても、毎回サインイン画面に戻ってしまいます。destroyCredentials() は、明示的な「サインアウト」または「リセット」ボタンから呼び出してください。

戻りの遷移では、SDK が消費する前に、location.search と location.hash の両方から code、error、error_description を読み取ってください。これらが存在するのに認証情報が得られない場合は、その理由を画面に表示してください。何も表示されずにサインイン画面へ戻るだけでは、ボタンが反応していない状態と見分けがつかず、原因の特定に時間がかかります。checkSignInStatus() の処理が完了してから、history.replaceState でこれらを取り除いてください。

実際のページでサインイン状態を確認する

ArcGIS Online のベースマップにトークンが必要な場合、サインインまでアプリを覆うゲートを設けるのが適切です。サインイン前には描画するものがないためです。実際のページで確認してください。basemap: "osm" と公開レイヤーを使うトークン不要のハーネスは、認証情報なしでマップ、レンダラー、凡例を検証できるため、作成する価値があります。ただし、ゲートが含まれないため、サインインが機能することは検証できません。ハーネスが正常でも、アプリが動作しているとは限りません。

ゲートに作成者指定の display ルール（display: grid、display: flex）がある場合、そのルールは hidden 属性の背後にあるユーザーエージェントの display: none を上書きします。そのため、gate.hidden = true を設定しても何も変わらず、完成したアプリはゲートの背後に隠れたままになります。[hidden] { display: none !important; } を追加してください。

API を提案する前に検証する

クラス、メソッド、プロパティを提案する前に、arcgis-docs-lookup で、固定したバージョンに存在することを確認してください。バージョンを移行する際は、メソッドが引き続き存在すると決めつけず、破壊的変更ガイドを読んでください。

破壊的な編集をガードする

データを削除または上書きするコードを出力する前に、（削除を伴う FeatureLayer.applyEdits、deleteFeatures、ライブレイヤーに接続したエディターウィジェットなど）、いったん作業を止め、次の項目を順番にすべて満たしてください。これは取り消せないデータ操作のみを対象とし、認証情報や組織の衛生管理は対象外です。

1. 対象を明示する。 操作対象となる組織／ポータルと、正確なアイテム ID またはレイヤー ID を明記します。対象が明示されていない場合は中止してください。
2. 対象の内容を示す。 レイヤーのタイトル、種類、フィーチャ数を表示し、ユーザーがこれから失う内容を確認できるようにします。
3. 本番環境ではないことを確認する。 その旨を明示し、処理を進める前にユーザーの確認を得ます。
4. まず取り消し可能な方法を優先する。 破壊的な呼び出しを実行する前に、影響範囲がわかるよう、読み取り専用のクエリまたは件数を提示します。
5. 確認なしで出力しない。 1～4 を満たし、ユーザーが確認するまでは、破壊的な呼び出しを出力しないでください。ユーザーが確信しているように見える場合も同様です。

この SDK での適用方法：レイヤー URL がハードコードされているか設定から読み込まれているか、また現在本番環境を指しているかを確認し、書き込みの前にアプリのフロー内で確認を行います。

完了条件

対象と SDK のバージョンがマトリックスから特定されていること、AMD の足場コードが残っていないこと、コンポーネント（または CSS を含むウィジェット）が意図的に選択されていること、Calcite のバージョンが互換性のあるものに固定されていること、提案するすべての API が固定したバージョンで検証されていること、破壊的な編集がすべてガードを通過していること。アプリでサインインを行う場合は、リダイレクト URL が推測ではなく登録または検証されていること、開発サーバーがその正確な URL を配信していること、destroyCredentials() がユーザー操作からのみ呼び出し可能であること、実際のページでサインインの一連の操作を行い、サインイン済み状態を確認できていること。