使用英语阅读

通过


文件

IIS 管理 API 提供一组与文件系统直接交互的文件 API。 这意味着,如果文件是最新的,则可以在本地或远程使用 API 来部署内容、进行编辑或检查。

常规文件 (/api/files)

/api/files 终结点公开计算机上的文件和目录的元数据和内容。 通过此 API 提供的文件仅限于 appsettings.json 文件的文件配置节中指定的文件。 在不指定目录的情况下查询 /api/files 终结点将列出配置中存在的位置。 这些位置表示通过 API 提供的所有文件系统路径的根。 只要文件路径具有执行操作所需的声明,就可以使用标准 HTTP post、delete 和 patch 谓词创建、删除和操作文件。

示例

文件

{
    "name": "iisstart.png",
    "id": "{id}",
    "type": "file",
    "physical_path": "C:\\inetpub\\wwwroot\\iisstart.png",
    "exists": "true",
    "size": "98757",
    "created": "2017-01-09T18:08:33.5130112Z",
    "last_modified": "2017-01-09T17:48:13.6180477Z",
    "last_access": "2017-01-09T17:48:13.6180477Z",
    "e_tag": "1d26aa08c67ed45",
    "parent": {
        "name": "wwwroot",
        "id": "{id}",
        "type": "directory",
        "physical_path": "C:\\inetpub\\wwwroot"
    },
    "claims": [
        "read",
        "write"
    ]
}

Directory

{
    "name": "wwwroot",
    "id": "{id}",
    "type": "directory",
    "physical_path": "C:\\inetpub\\wwwroot",
    "exists": "true",
    "created": "2017-01-09T18:08:33.1380257Z",
    "last_modified": "2017-01-30T17:01:15.2619212Z",
    "last_access": "2017-01-30T17:01:15.2619212Z",
    "total_files": "7",
    "parent": {
        "name": "inetpub",
        "id": "a-nA1LZCBZ9jIqxr6e2uWg",
        "type": "directory",
        "physical_path": "C:\\inetpub"
    },
    "claims": [
        "read",
        "write"
    ]
}

Web 服务器文件 (/api/webserver/files)

/api/webserver/files 终结点公开 IIS 创建的虚拟文件结构。 此终结点下的所有文件资源都属于某个网站,该文件的路径相对于它所属的网站。 这允许将网站视为文件系统根目录,这在 Web 服务器方案中是可取的。 虚拟目录包含在普通目录中,以获取网站的虚拟文件层次结构的完整视图。

所有 Web 服务器文件都有对 file_info 这是可从 /api/files 终结点获取的文件元数据的引用。

示例

Web 文件

{
    "name": "iisstart.png",
    "id": "{id}",
    "type": "file",
    "path": "/iisstart.png",
    "parent": {
        "name": "",
        "id": "{id}",
        "type": "application",
        "path": "/"
    },
    "website": {
        "name": "Default Web Site",
        "id": "{id}",
        "status": "started"
    },
    "file_info": {
        "name": "iisstart.png",
        "id": "{id}",
        "type": "file",
        "physical_path": "C:\\inetpub\\wwwroot\\iisstart.png"
    }
}

Web 目录

{
    "name": "imgs",
    "id": "{id}",
    "type": "directory",
    "path": "/imgs",
    "parent": {
        "name": "",
        "id": "{id}",
        "type": "application",
        "path": "/"
    },
    "website": {
        "name": "Default Web Site",
        "id": "{id}",
        "status": "started"
    },
    "file_info": {
        "name": "imgs",
        "id": "{id}",
        "type": "directory",
        "physical_path": "C:\\inetpub\\wwwroot\\imgs"
    }
}

复制/移动文件 (/api/files/copy |/api/files/move)

API 支持通过 /api/files/copy/api/files/move 终结点复制和移动文件。 复制文件的过程是通过对描述所需复制操作的 API 执行 POST 请求来执行的。

POST

{
  "name":"{optional name of the destination file}",
  "file": {
    "id": "{id property of the file to copy}"
  },
  "parent": {
    "id": "{id property of the directory to copy to}"
  }
}

(/api/files/content) 操作文件内容

/api/files 路由下的资源仅包含文件的元数据。 若要操作文件的内容,必须使用 /api/files/content/{id} 路由。 此路由使用 application/octet-stream 内容类型来传输数据。 对文件的内容 URL 执行 GET 请求将检索文件的原始字节。 此操作支持 HTTP 范围请求,因此可以分块下载文件。 对文件的内容 URL 执行 PUT 请求会将文件的内容替换为请求正文。 此操作支持 HTTP 内容范围请求,以启用文件的随机访问操作。

下载文件的第 2 个 500 字节

    GET /api/files/content/{id}
    Access-Token: Bearer {Access-Token}
    Range: bytes=500-999

编辑 1000 字节文件的 500 字节

    PUT /api/files/content/{id}
    Access-Token: Bearer {Access-Token}
    Content-Range: bytes 500-999/1000
    Content-Length: 500

下载文件 (/api/files/download)

可以通过 API 的 /api/files/content 终结点下载文件。 此终结点的缺点是,由于它位于 API 路由下,因此需要访问令牌。 这意味着无法通过浏览器下载该文件。 使用 /api/files/download 终结点可以创建临时下载链接。 这些下载链接是唯一的,是随机生成的,不需要访问令牌。 生成的下载链接采用 /downloads/{random_sequence} 的形式。 生成下载链接时,可以使用可选的生存时间 (ttl) 参数来指定下载链接的可用时间。 默认值为 5 秒。

生成下载时,将在 HTTP 响应的 Location 标头中返回下载链接。

POST

{
    "file": {
        "id": "{id of the file to download}"
    },
    "ttl": "10000"
}

使用文件共享

文件 API 可用于管理文件共享上的文件。 若要启用此功能,文件共享必须允许对表示运行 API 的计算机的主体拥有必要的文件系统权限。 例如,假设 \ \share\images 中有共享内容,我们希望允许在名为 web-prod-1 的 Web 服务器上运行的 API 来枚举这些文件。 若要允许此操作,管理员必须修改 \\share\images 目录的 ACL,以允许对 web-prod-1 Active Directory 对象的 READ 访问。 完成此操作后, Web-prod-1 计算机上的服务将能够访问此目录、读取文件,然后通过 API 公开这些文件。

位置 - 文件 API 根 (/api/files/locations)

API 的文件系统访问权限仅限于 appsettings 文件中指定的一组根文件夹(称为位置)。 从文件 API 的角度来看,这些位置显示为根,但在物理驱动器上,它们可能是嵌套文件夹、驱动器的根,甚至是网络共享。 对于每个位置,读取和写入访问权限都是独立控制的。 文件系统 API 不会看到文件系统上不属于某个位置的任何路径。

从版本 2.2.0 开始,可通过 /api/files/locations 终结点访问位置设置。 此终结点已锁定为 API 所有者用户组 中的用户。 这意味着需要 Windows 身份验证才能访问位置终结点。 添加或删除位置将添加或删除 API 中的文件系统访问。 此终结点支持 GET、PATCH、POST 和 DELETE,用于创建、编辑和删除现有位置。 编辑位置对物理文件没有影响,它只操作文件系统的 API 视图。

默认位置配置

{
    "locations": [
        {
            "alias": "inetpub",
            "id": "{id}",
            "path": "C:\\inetpub",
            "claims": [
                "read"
            ]
        }
    ]
}