此库提供Domino API的绑定。它随Domino标准环境（DSE）一起提供。

查看此文档了解API的详细信息

• 最新的公共Domino API

• 旧版API

python-domino的最新发布版本是1.4.2。

版本兼容性矩阵

python-domino库与不同版本的Domino兼容

Domino版本	Python-Domino
3.6.x或更低	0.3.5
4.1.0或更高	1.0.0或更高
5.3.0或更高	1.2.0或更高
5.5.0或更高	1.2.2或更高
5.10.0或更高	1.3.1或更高
5.11.0或更高	1.4.1或更高
6.0.0或更高	1.4.2或更高

开发

当前的python-domino基于Python 3.9，因此建议用于开发。《Pipenv》也建议用于管理依赖项。

要在Domino工作簿会话中使用Python绑定，请将dominodatalab包含在项目的requirements.txt文件中。这使得Python绑定在每个新工作簿会话（或批量运行）中可用。

为开发安装setup.py的依赖项

pipenv install -e ".[dev]"

使用相同的过程为Airflow和数据设置

pipenv install -e ".[data]" ".[airflow]"

设置连接

您可以通过创建一个新的Domino实例来设置连接。

_class_ Domino(project, api_key=None, host=None, domino_token_file=None, auth_token=None)

• 项目：项目标识符（以所有者用户名/项目名称的形式）。

• api_proxy：（可选）Domino API反向代理的位置，格式为主机：端口。

  如果设置了此代理，则用于拦截任何Domino API请求并插入身份验证令牌。这是首选的认证方法。作为替代，设置DOMINO_API_PROXY环境变量。在Domino 5.4.0或更高版本中，此变量在Domino运行容器内部设置。

  注意：此机制在连接到HTTPS端点时不起作用；它旨在在Domino运行内部使用。

• api_key：（可选）用于认证的API密钥。

  如果未提供，库期望在DOMINO_USER_API_KEY环境变量中找到它。如果您正在使用已在Domino中运行的Python包中的代码，则DOMINO_API_USER_KEY变量将自动设置为您启动运行的用户的密钥。

• 主机：（可选）主机URL。

  如果未提供，库期望在DOMINO_API_HOST环境变量中找到它。

• domino_token_file：（可选）包含认证令牌的Domino令牌文件的路径。

  如果未提供，库期望在DOMINO_TOKEN_FILE环境变量中找到它。如果您正在使用已在Domino中运行的Python包中的代码，则DOMINO_TOKEN_FILE将自动设置为您启动运行的用户的令牌文件。

• auth_token：（可选）认证令牌。

认证

Domino将按以下顺序查找认证方法，并使用找到的第一个

1. api_proxy
2. auth_token
3. domino_token_file
4. api_key
5. DOMINO_API_PROXY
6. DOMINO_TOKEN_FILE
7. DOMINO_USER_API_KEY

API代理是首选的认证方法。请参阅使用API代理来认证对Domino API的调用。

其他环境变量

• DOMINO_LOG_LEVEL

  默认日志级别是INFO。您可以通过设置DOMINO_LOG_LEVEL来更改日志级别，例如设置为DEBUG。

• DOMINO_VERIFY_CERTIFICATE

  出于测试目的和SSL证书问题，将DOMINO_VERIFY_CERTIFICATE设置为false。确保在使用后取消设置此变量。

• DOMINO_MAX_RETRIES

  默认重试次数设置为4。在发生ConnectionError时确定请求会话的重试次数。有关基于重试和退避因子的请求最大超时/错误持续时间的信息，请参阅此处

方法

预算和计费标签

请参阅example_budget_manager.py以获取示例代码。

budget_defaults_list()

获取具有分配的（如果有的话）限制的可用默认预算列表。需要管理员权限。

budget_defaults_update(budget_label, budget_limit)

通过预算标签更新默认预算。需要管理员角色。

• budget_label：（必需）要更新的预算标签，例如：BillingTag、Organization

• budget_limit：（必需）分配给默认标签的新预算配额

budget_overrides_list()

获取具有分配限制的可用预算覆盖列表。需要管理员权限。

budget_override_create(budget_label, budget_id, budget_limit)

基于预算标签创建预算覆盖，例如：计费标签、组织或项目，使用对象ID作为预算ID。需要管理员角色

• budget_label：要更新的预算标签

• budget_id：用作新预算覆盖ID的项目或组织ID。

• budget_limit: 分配给覆盖预算的预算配额

budget_override_update(budget_label, budget_id, budget_limit)

根据预算标签和预算 ID 更新预算覆盖。需要管理员角色

• budget_label：要更新的预算标签

• budget_id: 要更新的预算覆盖的 ID。

• budget_limit: 分配给覆盖的新预算配额

budget_override_delete(budget_id)

删除现有的预算覆盖。需要管理员角色

• budget_id: 要删除的预算覆盖的 ID。

budget_alerts_settings()

获取当前的预算警报设置。需要管理员权限

budget_alerts_settings_update(alerts_enabled, notify_org_owner)

更新当前的预算警报设置以启用/禁用预算通知以及是否在项目通知中通知组织所有者。需要管理员权限

• alerts_enabled: 是否启用或禁用通知。

• notify_org_owner: 是否在项目达到阈值时通知组织所有者。

budget_alerts_targets_update(targets)

根据预算标签更新当前的预算警报设置，为每个预算标签添加额外的电子邮件目标。需要管理员权限

• targets: 预算标签和电子邮件地址列表的字典

billing_tags_list_active()

获取活动计费标签列表。需要管理员权限

billing_tags_create(tags_list)

创建活动计费标签列表。需要管理员权限

• tags_list: 要创建的计费标签名称列表

active_billing_tag_by_name(name)

获取活动或存档计费标签的详细信息。需要管理员权限

• name: 现有计费标签的名称

billing_tag_archive(name)

存档活动计费标签。需要管理员权限

• name: 要存档的现有计费标签的名称

billing_tag_settings()

获取当前的计费标签设置。需要管理员权限

billing_tag_settings_mode()

获取当前的计费标签设置模式。需要管理员权限

billing_tag_settings_mode_update(mode)

更新当前的计费标签设置模式。需要管理员权限

• mode: 要设置计费标签设置的新模式（请参阅BillingTagSettingMode）

project_billing_tag(project_id)

通过项目 ID 获取分配给特定项目的计费标签。需要管理员权限

• project_id: 要查找分配计费标签的项目 ID

project_billing_tag_update(billing_tag, project_id)

使用新的计费标签更新项目的计费标签。需要管理员权限

• billing_tag: 要分配给项目的计费标签

• project_id: 要分配计费标签的项目 ID

project_billing_tag_reset(project_id)

从指定的项目中删除计费标签。需要管理员权限

• project_id: 重置计费标签字段的项目的 ID

projects_by_billing_tag( billing_tag, offset, page_size, name_filter, sort_by, sort_order, missing_tag_only=False)

从指定的项目中删除计费标签。需要管理员权限

• billing_tag: 用于过滤项目的计费标签字符串

• offset: 页面的起始索引，其中checkpointProjectId 是索引 0。如果偏移量为负，则指向的项目将是页面的末尾。

• page_size: 每页要返回的记录数。

• name_filter: 通过名称子串匹配项目

• sort_by: （可选）排序项目的字段

• sort_order: （可选）按升序或降序排序

• missing_tag_only: （可选）确定是否仅返回具有缺失标签的项目

project_billing_tag_bulk_update(projects_tag)

批量更新项目的计费标签。需要管理员权限

• projects_tag: 项目 ID 和计费标签的字典

项目

有关示例代码，请参阅 example_projects_usage.py。

project_create_v4(project_name, owner_id, owner_username, description, collaborators, tags, billing_tag, visibility=PUBLIC)

使用 v4 端点创建项目的较新版本，允许更多的可选字段。

• project_name: （必需）项目的名称。

• owner_id: （可选）新创建的项目所有者的用户 ID（必须为管理员才能为其他用户创建项目）owner_id 或 owner_username 可以使用，两者都不需要（默认为当前 owner_username）

• owner_username: (可选) 要创建的新项目的所有者用户名（创建其他用户的 projek 需要 admin 权限）可以使用 owner_id 或 owner_username，两者都不需要（默认为当前所有者用户名）

• description: (可选) 项目描述

• collaborators: (可选) 要添加到项目的协作者列表

• tags: (可选) 要添加到项目的标签列表

• billing_tag: (可选，除非 billingTag 设置模式为 Required) 要添加到项目以进行管理的活动计费标签

• visibility: (可选) (默认为公共) 项目可见性

project_create(project_name, owner_username=None)

使用给定的项目名称创建一个新的项目。

• project_name: 项目的名称。

• owner_username: (可选) 项目的所有者用户名。当您需要在组织下创建项目时，此参数很有用。

collaborators_get()

获取项目上的协作者列表。

collaborators_add(username_or_email, message="")

将协作者添加到项目。

• username_or_email: 要添加为当前项目协作者的 Domino 用户的名称或电子邮件。

• message: 可选 - 与用户在项目中的角色或目的相关的消息。

项目标签

项目标签是向项目添加自由形式元数据的一种简单方法。标签有助于同事和消费者组织并找到他们感兴趣的项目。标签可以用来描述项目探索的主题、它使用的包和库或数据源。

有关示例代码，请参阅 example_projects_usage.py。

tags_list(*project_id)

列出项目的标签。

• project_id: 项目标识符。

tag_details(tag_id)

获取标签的详细信息。

• tag_id: 标签标识符。

tags_add(tags, *project_id)

如果不存在，则创建标签并将其添加到项目。

• tags (list): 一个或多个标签名称。

• project_id: (默认为当前项目 ID) 项目标识符。

tag_get_id(tag_name, *project_id)

使用标签字符串名称获取标签 ID。

• tag_name (string): 标签名称。

• project_id: (默认为当前项目 ID) 项目 ID。

tags_remove(tag_name, project_id=None)

从项目中删除标签。

• tag_name (string): 标签名称。

• project_id: (默认为当前项目 ID) 项目 ID。

执行

查看以下代码示例文件

• start_run_and_check_status.py

• export_runs.py

runs_list()

列出选定项目上的执行。

runs_start(command, isDirect, commitId, title, tier, publishApiEndpoint)

在选定项目上启动新的执行。

• command: 执行的命令，作为字符串数组，其中数组的成员代表命令的参数。例如：["main.py", "hi mom"]

• isDirect: (可选) 此命令是否应直接传递给 shell。

• commitId: (可选) 要从中启动的 commitId。如果不提供，项目从最新提交启动。

• title: (可选) 执行的标题。

• tier: (可选) 用于执行的硬件层。这是硬件层的可读名称，例如 "免费"、"小型" 或 "中型"。如果不提供，则使用项目的默认层。

• publishApiEndpoint: (可选) 是否从输出结果发布 API 端点。

runs_start_blocking(command, isDirect, commitId, title, tier, publishApiEndpoint, poll_freq=5, max_poll_time=6000)

在选定项目上启动新的执行并发出阻塞请求，等待作业完成。

• command: 执行的命令，作为字符串数组，其中数组的成员代表命令的参数。例如：["main.py", "hi mom"]

• isDirect: (可选) 此命令是否应直接传递给 shell。

• commitId: (可选) 要从中启动的 commitId。如果不提供，项目从最新提交启动。

• title: (可选) 执行的标题。

• tier: (可选) 用于执行的硬件层。如果没有提供，将使用项目的默认层。

• publishApiEndpoint: (可选) 是否从输出结果发布 API 端点。

• poll_freq: (可选) 轮询Domino服务器以获取正在运行的任务状态之间的秒数。

• max_poll_time: (可选) 等待任务完成的秒数最大值。如果超过此阈值，将引发异常。

• retry_count: (可选) 轮询重试的最大次数（在发生短暂的HTTP错误的情况下）。如果超过此阈值，将引发异常。

run_stop(runId, saveChanges=True)

停止选定项目中现有的执行。

• runId: 标识执行的字符串。

• saveChanges: (默认为True) 如果为false，则丢弃执行结果。

runs_stdout(runId)

获取特定执行的stdout输出。

• runId: 标识执行的字符串。

文件和blob

查看以下代码示例文件

• upload_file.py

• upload_and_run_file_and_download_results.py

files_list(commitId, path)

列出Domino项目文件夹中的文件。

• commitId: 要列出文件的commitId。

• path: (默认为"/") 列出的路径。 (默认为"/") 列出的路径。

files_upload(path, file)

将Python文件对象上传到项目中的指定路径。有关示例，请参阅examples/upload_file.py。所有参数都是必需的。

• path: 将文件保存到的路径。例如，/README.md将写入项目的根目录，而/data/numbers.csv将文件保存到名为data的子文件夹中。如果指定的文件夹尚不存在，则将其创建。

• file: Python文件对象。例如：f = open("authors.txt","rb")

blobs_get(key)

已弃用 通过blob键从Domino服务器检索文件。请改用blobs_get_v2(path, commit_id, project_id)。

• key: 从blob服务器获取文件的键。

blobs_get_v2(path, commit_id, project_id)

从项目的路径和提交ID中检索Domino服务器上的文件。

• path: Domino项目中的文件路径。
• commit_id: 从中检索文件的提交ID。
• project_id: 从中检索文件的项目的ID。

应用程序

app_publish(unpublishRunningApps=True, hardwareTierId=None)

在项目中发布应用程序，或重新发布现有应用程序。

• unpublishRunningApps: (默认为True) 在重新/发布之前检查当前项目中是否有活动应用程序实例并取消发布。

• hardwareTierId: (可选) 在指定的硬件层上启动应用程序。

app_unpublish()

停止项目中的运行应用程序。

作业

job_start(command, commit_id=None, hardware_tier_name=None, environment_id=None, on_demand_spark_cluster_properties=None, compute_cluster_properties=None, external_volume_mounts=None, title=None)

在项目中启动新的作业（执行）。

• command (字符串): 作业中要执行的命令。例如：domino.job_start(command="main.py arg1 arg2")

• commit_id (字符串): (可选) 要从中启动的commitId。如果不提供，作业将从最新的提交启动。

• hardware_tier_name (字符串): (可选) 要在其中启动作业的硬件层名称。如果不提供，则使用项目的默认层。

• environment_id (字符串): (可选) 要启动作业的环境ID。如果不提供，则使用项目的默认环境。

• on_demand_spark_cluster_properties (字典): (可选) 按需spark集群属性。以下属性可以在Spark集群中提供

  {
      "computeEnvironmentId": "<Environment ID configured with spark>"
      "executorCount": "<Number of Executors in cluster>"
       (optional defaults to 1)
      "executorHardwareTierId": "<Hardware tier ID for Spark Executors>"
       (optional defaults to last used historically if available)
      "masterHardwareTierId":  "<Hardware tier ID for Spark master"
       (optional defaults to last used historically if available)
      "executorStorageMB": "<Executor's storage in MB>"
       (optional defaults to 0; 1GB is 1000MB Here)
  }
  

• param compute_cluster_properties (字典): (可选) 计算集群属性定义包含启动任何Domino支持的计算集群作业的参数。请使用此参数启动使用计算集群的作业，而不是已弃用的on_demand_spark_cluster_properties字段。如果同时存在on_demand_spark_cluster_properties和compute_cluster_properties，则忽略on_demand_spark_cluster_properties。compute_cluster_properties包含以下字段

  {
      "clusterType": <string, one of "Ray", "Spark", "Dask", "MPI">,
      "computeEnvironmentId": <string, The environment ID for the cluster's nodes>,
      "computeEnvironmentRevisionSpec": <one of "ActiveRevision", "LatestRevision",
      {"revisionId":"<environment_revision_id>"} (optional)>,
      "masterHardwareTierId": <string, the Hardware tier ID for the cluster's master node (required unless clusterType is MPI)>,
      "workerCount": <number, the total workers to spawn for the cluster>,
      "workerHardwareTierId": <string, The Hardware tier ID for the cluster workers>,
      "workerStorage": <{ "value": <number>, "unit": <one of "GiB", "MB"> },
      The disk storage size for the cluster's worker nodes (optional)>
      "maxWorkerCount": <number, The max number of workers allowed. When
      this configuration exists, autoscaling is enabled for the cluster and
      "workerCount" is interpreted as the min number of workers allowed in the cluster
      (optional)>
  }
  

• external_volume_mounts (List[string]): （可选）外部卷挂载ID，用于挂载到执行中。如果未提供，则作业启动时不会挂载外部卷。

• *title (string): (可选) 作业的标题。

job_stop(job_id, commit_results=True)

停止项目中的作业（执行）。

• job_id (string): 作业标识符。

• commit_results (boolean): （默认为 true）如果为 false，则作业结果不会被提交。

job_status(job_id)

获取作业的状态。

• job_id (string): 作业标识符。

job_start_blocking(poll_freq=5, max_poll_time=6000, **kwargs)

启动一个作业并轮询直到作业完成。此外，此方法支持 job_start 方法中的所有参数。

• poll_freq: 轮询频率间隔，以秒为单位。

• max_poll_time: 最大轮询时间，以秒为单位。

数据集

Domino数据集是用户执行中可用的一组文件，作为一个文件系统目录。数据集始终反映数据的最新版本。您可以通过Domino UI或通过工作负载执行修改数据集的内容。

有关更多详细信息，请参阅Domino数据集，以及示例代码example_dataset.py。

datasets_list(project_id=None)

提供所有可用数据集的JSON列表。

• project_id (string): （默认为 None）项目标识符。每个项目最多可以包含5个数据集。

datasets_ids(project_id)

列出特定项目的数据集ID。

• project_id: 项目标识符。

datasets_names(project_id)

列出特定项目的数据集名称。

• project_id: 项目标识符。

datasets_details(dataset_id)

提供有关数据集的详细信息。

• dataset_id: 数据集标识符。

datasets_create(dataset_name, dataset_description)

创建一个新的数据集。

• dataset_name: 新数据集的名称。注意：名称必须是唯一的。

• dataset_description: 数据集的描述。

datasets_update_details(dataset_id, dataset_name=None, dataset_description=None)

更新数据集的名称或描述。

• dataset_id: 数据集标识符。

• dataset_name: （可选）数据集的新名称。

• dataset_description: （可选）数据集的新描述。

datasets_remove(dataset_ids)

删除一组数据集。

• dataset_ids (list[string]): 要删除的数据集ID列表。注意：数据集首先被标记为删除，然后在宽限期内（15分钟，可配置）删除。Domino管理员可能还需要完成此过程，才能重用该名称。

datasets_upload_files(dataset_id, local_path_to_file_or_directory, file_upload_setting, max_workers, target_chunk_size, target_relative_path)

将文件或整个目录上传到数据集。

• dataset_id: 数据集标识符。
• local_path_to_file_or_directory: 本地计算机中文件或目录的路径。
• file_upload_setting: 冲突解决设置，必须是 Overwrite、Rename、Ignore（默认）之一。
• max_workers: 最大线程数（默认：10）。
• target_chunk_size: 分片上传的最大块大小（默认：8MB）。
• target_relative_path: 上传文件或目录到数据集上的路径。注意，该路径必须存在，否则上传将失败。

Airflow

《python-domino》客户端附带了一个Operator，可与Apache Airflow一起使用。

从PyPI安装客户端时，将airflow标志添加到额外内容中

pip install "dominodatalab[airflow]"

类似地，从GitHub安装客户端时，使用以下命令

pip install -e git+https://github.com/dominodatalab/python-domino.git@1.0.6#egg="dominodatalab[airflow]"

有关示例代码，请参阅example_airflow_dag.py

DominoOperator

from domino.airflow import DominoOperator

允许用户通过Airflow安排Domino执行。与domino.runs_start具有相同的功能签名，并额外两个参数

• startup_delay: Optional[int] = 10 | 在您的作业中添加启动延迟，如果您希望在其他工作完成后才执行，则非常有用。
• include_setup_log: Optional[bool] = True | 确定是否在 stdout 前发布作业的设置日志作为日志前缀。

DominoSparkOperator

from domino.airflow import DominoSparkOperator

允许用户通过 v4 API 调度 Domino 执行，支持 onDemandSparkClusters。与 domino.job_start 具有相同的函数签名，并增加了上述 startup_delay。

示例

from domino import Domino

# By and large your commands will run against a single project,
# so you must specify the full project name
domino = Domino("chris/canon")

# List all runs in the project, most-recently queued first
all_runs = domino.runs_list()['data']

latest_100_runs = all_runs[0:100]

print(latest_100_runs)

# all runs have a commitId (the snapshot of the project when the
# run starts) and, if the run completed, an "outputCommitId"
# (the snapshot of the project after the run completed)
most_recent_run = all_runs[0]

commitId = most_recent_run['outputCommitId']

# list all the files in the output commit ID -- only showing the
# entries under the results directory.  If not provided, will
# list all files in the project.  Or you can say path=“/“ to
# list all files
files = domino.files_list(commitId, path='results/')['data']

for file in files:
print file['path'], '->', file['url']

print(files)

# Get the content (i.e. blob) for the file you're interested in.
# blobs_get returns a connection rather than the content, because
# the content can get quite large and it's up to you how you want
# to handle it
print(domino.blobs_get(files[0]['key']).read())

# Start a run of file main.py using the latest copy of that file
domino.runs_start(["main.py", "arg1", "arg2"])

# Start a "direct" command
domino.runs_start(["echo 'Hello, World!'"], isDirect=True)

# Start a run of a specific commit
domino.runs_start(["main.py"], commitId="aabbccddee")

手动安装

由于 python-domino 随 DSE 一起提供，通常您不需要安装它。
本节提供了在其他环境中安装或更新到较新版本的说明。

从版本 1.0.6 开始，python-domino 作为 dominodatalab 在 PyPI 上提供。

pip install dominodatalab

如果您正在将 python-domino 的安装说明添加到您的 Domino 环境 Dockerfile 指令字段中，您必须在开始处添加 RUN。

RUN pip install dominodatalab

从 PyPI 安装特定版本的库，例如 1.0.6

pip install dominodatalab==1.0.6

从 GitHub 安装特定版本的库，例如 1.0.6

pip install https://github.com/dominodatalab/python-domino/archive/1.0.6.zip

许可协议

此库根据 Apache 2.0 许可协议提供。这是一个 Domino Data Lab 的开源项目。