请求API (.requests)#
预计阅读时间：5分钟
你将学习的内容#
本指南旨在解释数据所有者与数据科学家协作中请求的使用方法。
简介#
数据所有者的角色是决定如何开放对其服务器和资产(如数据集或模型)的访问权限。然而，PySyft不是预先限制数据科学家只能执行一组允许的操作，而是通过允许数据科学家请求对其权限范围内的操作进行非常具体的更改，从而提供更大的灵活性。这些请求被称为requests。
请求是如何构建的？#
请求组件#
一个请求包含两个主要功能组件:
一个
sy.Change，这是请求的主题（request.changes）。下文将对此进行更详细的说明。一个
sy.RequestStatus，表示变更是否被应用。它可以是Approved（已批准）、Pending（待处理）或Denied（已拒绝）。(request.status)
请求工作流程#
一般来说，PySyft中的请求工作流程包括：
(1) 提交: 在相应的API上创建请求（例如
client.code,client.images），声明所需的输出。(2) 审核与批准: 数据所有者必须对请求进行适当审查，从安全和隐私角度理解批准该请求的影响。数据所有者可以决定批准或拒绝。如果批准，请求中提出的变更将应用于目标对象。
(3) 变更生效: 如果获得批准，所应用的变更将对提出请求的数据科学家可见。
以下是一个代码请求的示例。所有请求都遵循相同的执行模式。
请求与变更类型#
请求可以由服务器的用户发起，根据请求类型的不同，它们包含预定义的"变更"。sy.Change关联现有的Syft对象(change.linked_obj)并封装对该对象的特定类型修改。虽然上述内容略显抽象，但PySyft目前已借助变更机制实现了多种请求类型：
代码请求: 这些请求使用了最常见的变更类型，称为
UserCodeStatusChange，它允许数据科学家请求执行特定Syft函数的权限（可通过request.code获取）。具体来说，当UserCode与特定的Syft Policies配对时，用户可以请求在附加的输入和输出策略允许范围内执行该代码的权限。此类策略至少必须说明计算针对的资产以及可以执行的次数。
自定义工作池请求: 这些请求依赖于
CreateCustomWorkerPoolChange变更，它允许数据科学家在服务器上从现有的自定义镜像请求创建新资源（即工作池），从而使数据科学家可以在运行所需Python包的容器中执行代码，并可能根据提议的工作池规模进一步扩展。请注意，这里的请求也能够启动资源。更多详情请参阅即将发布的images API指南。自定义镜像与工作池请求: 这类请求包含两项变更:
CreateCustomImageChange和CreateCustomWorkerPoolChange。这使得数据科学家不仅能像上述请求那样从镜像创建自定义工作池，还能在现有镜像无法满足需求时，同时指定包含所需软件的新镜像定义。关联请求: 这些请求涉及
AssociationRequestChange变更，允许数据所有者在外部Datasite服务器上提交请求，创建与该服务器通信的单向路由。这需要拥有该服务器的外部数据所有者的批准。更多详情请参阅即将发布的网络指南。操作对象权限请求: 这些请求涉及
ActionStoreChange变更，允许数据科学家请求服务器上特定ActionObject的READ权限。该对象是存储在PySyft中或通过计算生成的数据包装对象。更多详情请参阅action API guide。
现在让我们看看如何创建一个代码请求。我们将很快记录如何创建其他类型的请求，因为其余请求目前处于测试阶段。
创建代码请求#
我们将首先运行一些设置代码以启用代码请求创建。
Show code cell source
import numpy as np
import syft as sy
server = sy.orchestra.launch(name="my_server", port="auto", dev_mode=False, reset=True)
do_client = server.login(email="[email protected]", password="changethis")
do_client.register(
email="[email protected]", name="John Doe", password="pw", password_verify="pw"
)
ds_client = server.login(email="[email protected]", password="pw")
dataset = sy.Dataset(
name="Dataset name",
description="**Placehoder Dataset description**",
asset_list=[sy.Asset(
name="asset_name",
data=[1,2,3], # real data
mock=[4,5,6], # mock data
)],
)
do_client.upload_dataset(dataset)
通过查阅代码API指南，我们可以构建一个虚拟的Syft函数包含在我们的请求中：
@sy.syft_function_single_use(x=ds_client.datasets[0].assets[0])
def my_dummy_func(x):
return x+1
创建代码请求的方式#
目前在PySyft中有两种方式可以创建此类代码执行请求：
直接通过代码API
在项目范围内
直接通过代码API#
ds_client.code.request_code_execution(my_dummy_func)
项目范围内#
# Create a project
project = sy.Project(
name="Dummy project",
description="I am doing a dummy project for illustrating code requests.",
members=[ds_client],
).send()
project
project.create_code_request(my_dummy_func)
查看请求#
所有请求，无论其类型和目的，都可以通过PySyft提供的Requests API查看。
与其他API类似，管理员或数据所有者可以查看提交到其服务器的所有请求，而数据科学家只能查看自己提交的请求：
ds_client.requests
我们可以像这样索引每个单独的请求：
request = ds_client.requests[0]
request
如果感兴趣，您还可以查看具体的变更类型以及与之关联的对象：
request.changes[0]
request.changes[0].linked_obj
请求元数据#
更多元数据可通过sy.Request对象获取，例如：
谁创建了这个请求：
requesting_user_name: 创建请求的用户requesting_user_email: 请求用户的电子邮件requesting_user_institution: 请求用户所属的机构requesting_user_verify_key: 请求用户的系统生成验证密钥
修改时间：
request_time: 请求创建的时间updated_at: 请求最后更新的时间（例如其状态）history: 包含请求状态变更的日志记录
创建位置：
server_uid: 创建请求的服务器的UID
谁批准了该请求：
request.approving_user_verifying_key: 系统生成的审批用户验证密钥
ds_client.requests[0].changes[0].linked_obj
响应请求#
只有管理员或数据所有者拥有批准或拒绝请求的权限。
他们的责任是确保批准不会带来隐私或安全问题，并且符合其发布数据的内部规则。如果不符合，数据所有者有权拒绝请求。
审核步骤#
do_client.requests[0]
request = do_client.requests[0]
request.code
审批步骤#
这可以通过.approve和.deny API实现。但请注意，代码请求可能表现不同，具体取决于部署设置。如果设置仅包含一个同时拥有模拟数据和私有数据的服务器（高安全节点），数据所有者可以直接执行：
request.approve()
或者拒绝：
request.deny(reason="This imposes privacy risks")
然而，当请求在物理隔离系统上创建时，批准是同步流程的隐含部分，而拒绝操作同样发生在请求创建处（低安全区）。您可以在同步API中了解更多关于整个流程的信息。