Back to Details

python-notebook

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ArcGIS API for Python & ArcGIS Notebooks

ArcGIS API for Python & ArcGIS Notebooks

Determine the runtime target first

先确定运行时目标

The runtime pins the library versions — you do not choose them independently. Establish which target applies before importing anything, because the rules diverge from here:
  • Hosted ArcGIS Notebooks (Enterprise or Online)
  • Local / conda / pip environment
运行时会固定库版本——你无法独立选择版本。在导入任何内容之前，请先确定适用的目标环境，因为不同环境的规则有所不同：
  • 托管ArcGIS Notebooks（企业版或在线版）
  • 本地 / conda / pip 环境

Hosted notebooks: check the runtime manifest

托管Notebook：查看运行时清单

Hosted runtimes are versioned to match the Notebook Server version (e.g. "ArcGIS Notebook Server Standard 12.0"). Two runtimes ship as container images:
  • Standard
  • Advanced — everything in Standard plus ArcPy.
ArcPy is Advanced-only: a notebook switched to Standard errors on any ArcPy cell. Authoring with each runtime is gated by a separate portal privilege. Check the runtime manifest for the target version before importing — do not assume a library is present, and do not pip-install around the runtime.
托管运行时的版本与Notebook Server版本匹配（例如“ArcGIS Notebook Server Standard 12.0”）。有两种运行时以容器镜像形式提供：
  • Standard（标准版）
  • Advanced（高级版） —— 包含标准版的所有内容外加ArcPy。
ArcPy仅适用于高级版：切换到标准版的Notebook在运行任何ArcPy代码单元时都会报错。使用每种运行时进行创作需要单独的门户权限。在导入库之前，请查看目标版本的运行时清单——不要假设某个库已存在，也不要绕过运行时使用pip安装。

Changing the runtime can break working code

更改运行时可能会破坏正常运行的代码

Precedent: arcgis 2.4.0 introduced a new map widget for Jupyter Notebook 7 / JupyterLab 4, and code written against the old widget requires migration; staying on arcgis 2.3.1 keeps Jupyter Notebook 6. Flag this risk before switching a notebook's runtime, and confirm the current behavior against the release notes for the versions in play.
先例：arcgis 2.4.0为Jupyter Notebook 7 / JupyterLab 4引入了新的地图小部件，针对旧小部件编写的代码需要迁移；而停留在arcgis 2.3.1版本则会保留Jupyter Notebook 6。在切换Notebook的运行时之前，请标记此风险，并对照相关版本的发行说明确认当前代码的兼容性。

Local installs: pin Python to the library

本地安装：将Python版本与库绑定

arcgis 2.4.2+ requires Python 3.10.x–3.13.x. Verify the exact range against the system-requirements page for the version in use rather than assuming.
arcgis 2.4.2+要求Python版本为3.10.x–3.13.x。请根据所使用版本的系统要求页面确认确切的版本范围，不要自行假设。

Watch deprecated modules

注意已弃用的模块

GeoAnalytics Server's final release was Enterprise 11.3; 
arcgis.geoanalytics
is supported via the built-in Python API only through 11.3 and earlier. Do not target it on newer releases.
GeoAnalytics Server的最终版本为Enterprise 11.3；
arcgis.geoanalytics
仅在11.3及更早版本中通过内置Python API提供支持。请勿在新版本中使用该模块。

Auth: match the environment, never inline credentials

身份验证：匹配环境，绝不硬编码凭证

  • Inside a hosted notebook, authenticate with 
    GIS("home")
    .
  • Elsewhere, use explicit credential auth — but never write credentials inline; source them from the environment or a prompt.
  • 在托管Notebook中，使用
    GIS("home")
    进行身份验证。
  • 在其他环境中，使用显式凭证验证——但绝不硬编码凭证；应从环境变量或提示中获取凭证。

Guard destructive operations

防范破坏性操作

Before generating any code that calls 
truncate
, 
delete
, 
delete_features
, 
overwrite
, or removes an item or layer, stop and satisfy every point in order. This covers irreversible data operations only, not credentials or org hygiene.
  1. Name the target. State the org and the exact item or layer id the call targets. An unnamed target is a stop.
  2. Show what it is. Display the target's title, type, and feature count so the user sees what they are about to lose.
  3. Confirm it is not production. Say so explicitly and get the user's confirmation before proceeding.
  4. Prefer the reversible form first. Offer a query-first / count-first or dry-run form so the blast radius is known before the destructive call runs.
  5. Never emit blind. Withhold the destructive call until 1–4 are satisfied and the user confirms — even when the user sounds confident.
在生成任何调用
truncate
、
delete
、
delete_features
、
overwrite
或删除项/图层的代码之前，请按顺序完成以下所有步骤。这仅适用于不可逆的数据操作，不适用于凭证或组织管理操作。
  1. 明确目标对象。说明操作针对的组织以及确切的项或图层ID。未明确目标的操作必须停止。
  2. 展示目标信息。显示目标对象的标题、类型和要素数量，让用户清楚他们即将丢失的内容。
  3. 确认非生产环境。明确说明这一点，并在继续操作前获得用户的确认。
  4. 优先选择可逆形式。先提供查询优先/计数优先或试运行形式，以便在执行破坏性操作前了解影响范围。
  5. 绝不盲目执行。在完成1-4步骤并获得用户确认之前，不要执行破坏性操作——即使用户看起来很有把握。

Done when

完成标准

The runtime target is identified; libraries are confirmed present in that runtime (or Python is pinned for a local install); auth matches the environment with no inline credentials; and any destructive call has passed through the guard.
已确定运行时目标；确认该运行时中存在所需库（或本地安装已绑定正确的Python版本）；身份验证方式与环境匹配且无硬编码凭证；所有破坏性操作均已通过防范检查。