将可管理性应用程序与Microsoft 365 应用版即点即用安装程序集成

2024-04-13

了解如何将Microsoft 365 应用版即点即用安装程序与软件管理解决方案集成。

Microsoft 365 应用版即点即用安装程序提供 COM 界面，允许 IT 专业人员和软件管理解决方案以编程方式控制更新管理。此接口提供除 Office 部署工具提供的功能之外的其他管理功能。

注意

本文适用于使用即点即用安装程序的 Office 应用。

与即点即用集成

若要使用此接口，可管理性应用程序会调用 COM 接口，并调用与即点即用安装服务直接通信的公开 API。

注意

Office 即点即用安装程序可以从命令行运行，其参数可以控制行为，如 Office 即点即用部署工具中所述。

下面是 COM 接口的概念图

在 Office 即点即用安装程序上使用 COM 界面的关系图。

Microsoft 365 应用版即点即用安装程序实现注册到 CLSID CLSID_UpdateNotifyObject的基于 COM 的接口 IUpdateNotify。

可按如下所示调用此接口：

hr = CoCreateInstance(CLSID_UpdateNotifyObject, NULL, CLSCTX_ALL,
       IID_IUpdateNotify, 
      (void **)&p);

仅当调用方以提升的权限运行时，调用才会成功，因为必须使用提升的权限运行即点即用安装程序。

IUpdateNotify COM 接口公开了三个异步函数，这些函数负责使用即点即用安装服务验证命令和参数以及计划执行。

HRESULT Download([in] LPWSTR pcwszParameters) // Download update content.
HRESULT Apply([in] LPWSTR pcwszParameters) // Apply update content.
HRESULT Cancel() // Cancel the download action.

第四种方法 Status 可用于获取有关上次执行命令的状态或当前正在执行的命令的状态 (的信息，即成功、失败、详细错误代码) 。

HRESULT status([out] _UPDATE_STATUS_REPORT* pUpdateStatusReport) // Get status of current action. 
typedef struct _UPDATE_STATUS_REPORT  
{  
UPDATE_STATUS status;  
UINT error; 
BSTR contentid;  
} UPDATE_STATUS_REPORT;

即点即用安装服务在其生命周期内可能处于四种状态，在此期间，可能会调用 IUpdateNotify 方法：正在重新启动、空闲、下载和应用。

下面是 COM 接口状态机关系图

COM 接口的状态图。

注意

重新启动：当计算机启动时，有一段时间的即点即用安装程序服务不可用。重新启动后成功调用 Status 方法将返回eUPDATE_UNKNOWN。

闲置： 当即点即用安装程序处于空闲状态时，可以调用：

应用：安装以前下载的内容。
取消：返回 0x800000e，“在意外时间调用了方法。
下载：将新内容下载到客户端以供以后安装。
状态：返回上次完成的操作的结果，如果操作以失败告终，则返回错误消息。如果没有上一个操作， 则 Status 返回 eUPDATE_UNKNOWN。

下载： 当即点即用安装程序处于下载状态时，可以调用：

Apply：返回值为 0x800000e“在意外时间调用了方法”的 HRESULT。
取消：停止下载并删除部分下载的内容。
下载：返回值为 0x800000e“在意外时间调用了方法”的 HRESULT。
状态：返回指示下载工作正在进行 DOWNLOAD_WIP 。

应用： 当即点即用安装程序正在安装之前下载的内容时：

Apply：返回值为 0x800000e“在意外时间调用了方法”的 HRESULT。
取消：返回 0x800000e，无法取消“应用”操作。
下载：返回值为 0x800000e“在意外时间调用了方法”的 HRESULT。
状态：返回指示应用工作正在进行 APPLY_WIP 。

注意

由于 OfficeC2RCOM 是一个 COM+ 服务并且是动态加载的，因此每次调用此类上的方法时，都需要调用 CoCreateInstance ，以确保获得预期结果。如有必要，COM+ 服务将处理创建新实例。首次调用其中一个方法时，COM+ 将加载 IUpdateNotify 对象并在 dllhost.exe 实例之一中运行它。新对象将在空闲状态中保持活动状态约 3 分钟。如果在上次调用后的三分钟内进行了后续调用， 则 IUpdateNotify 对象将保持加载状态，并且不会创建新实例。如果在三分钟内未进行调用，则会卸载 IUpdateNotify 对象，并在下一次调用时创建新的 IUpdateNotify 对象。

即点即用安装程序 COM API 参考指南

在以下 API 参考文档中：

参数采用键/值对格式，用空格分隔。
参数不区分大小写。
有关详细信息，请参阅有关 Office 即点即用安装和相关的反恶意软件应用程序的信息。
现在包含 IUpdateNotify2 接口的摘要。

应用

HRESULT Apply([in] LPWSTR pcwszParameters) // Apply update content.

参数

displaylevel： 如果为 true ，则显示更新过程中的安装状态，包括错误; 如果为 false ，则隐藏更新过程中的安装状态（包括错误）。默认值为 false。
forceappshutdown： 如果为 true ，则强制在触发 “应用” 操作时立即关闭 Office 应用程序;如果正在运行任何 Office 应用程序， 则为 false ，则失败。默认值为 false。有关详细信息，请参阅备注。

如果在触发 “应用” 操作时正在运行任何 Office 应用程序， “应用” 操作通常会失败。传递给 forceappshutdown=trueApply 方法将导致 OfficeClickToRun 服务立即关闭应用程序并应用更新。在这种情况下，用户可能会遇到数据丢失的情况。

返回结果

结果	说明
S_OK	操作已成功提交到即点即用服务以执行。
E_ACCESSDENIED	调用方未使用提升的权限运行。
E_INVALIDARG	传递的参数无效。
E_ILLEGAL_METHOD_CALL	目前不允许执行操作。有关详细信息，请参阅备注。

备注

如果在触发 “应用” 操作时正在运行任何 Office 应用程序， “应用” 操作将失败。 forceappshutdown=true传递给 Apply 方法将导致 OfficeClickToRun 服务立即关闭正在运行的任何 Office 应用程序并应用更新。用户可能会遇到数据，因为系统不会提示他们保存对打开的文档所做的更改。
仅当 COM 状态为以下情况之一时，才能触发此操作：
- eUPDATE_UNKNOWN
- eDOWNLOAD_CANCELLED
- eDOWNLOAD_FAILED
- eDOWNLOAD_SUCCEEDED
- eAPPLY_SUCCEEDED
- eAPPLY_FAILED
如果调用 Apply 方法时未下载内容， 则 Apply 方法将报告 “成功 ”，因为它未检测到要应用的内容，并成功完成 了 Apply 过程。

取消

HRESULT Cancel() // Cancel the download action.

返回结果

结果	说明
S_OK	操作已成功提交到即点即用服务以执行。
E_ILLEGAL_METHOD_CALL	目前不允许执行操作。有关详细信息，请参阅 “备注 ”部分

备注

仅当 COM 状态 ID eDOWNLOAD_WIP 时，才能触发此方法。它将尝试取消当前下载操作。 COM 状态将更改为 eDOWNLOAD_CANCELLING ，最终更改为 eDOWNLOAD_CANCELED。如果在任何其他时间触发，COM 状态将返回 E_ILLEGAL_METHOD_CALL 。

下载

HRESULT Download([in] LPWSTR pcwszParameters) // Download update content.

参数

displaylevel： 如果为 true ，则显示更新过程中的安装状态，包括错误; 如果为 false ，则隐藏更新过程中的安装状态（包括错误）。默认值为 false。
updatebaseurl：备用下载源的 URL。
updatetoversion：要将 Office 更新到的版本。如果要更新到比当前安装的版本更早的版本，请定义此参数。
downloadsource：自定义 IBackgroundCopyManager 实现的 CLSID (BITS manager) 。
contentid：标识要通过自定义 BITS 管理器从内容服务器下载的内容。此值通过 BITS 接口传递以供解释。

返回结果

结果	说明
S_OK	操作已成功提交到即点即用服务以执行。
E_ACCESSDENIED	调用方未使用提升的权限运行。
E_INVALIDARG	传递的参数无效。
E_ILLEGAL_METHOD_CALL	目前不允许执行操作。有关详细信息，请参阅备注。

备注

必须将 downloadsource 和 contentid 指定为一对。否则， Download 方法将返回 E_INVALIDARG 错误。
如果提供了 downloadsource、 contentid 和 updatebaseurl ，则将忽略 updatebaseurl 。
仅当 COM 状态为以下情况之一时，才能触发此操作：
- eUPDATE_UNKNOWN
- eDOWNLOAD_CANCELLED
- eDOWNLOAD_FAILED
- eDOWNLOAD_SUCCEEDED
- eAPPLY_SUCCEEDED
- eAPPLY_FAILED
如果在调用 Apply 方法时没有以前下载的内容， 则 Apply 方法将报告 “成功 ”，因为它未检测到任何要应用的内容，并成功完成 了“应用” 过程。

示例

若要从自定义的 BITS 管理器下载内容，请调用传递以下参数 的下载 () 函数：
```
"downloadsource=CLSIDofBITSInterface contentid=BITSServerContentIdentifier"
```
若要从 Office 内容分发网络 (CDN) 下载内容：在不指定 downloadsource、contentid 或 updatebaseurl 参数的情况下调用 download () 函数。
若要从自定义位置下载内容：调用传递以下参数 的下载 () 函数：
```
"updatebaseurl=yourcontentserverurl"
```

状态

typdef struct _UPDATE_STATUS_REPORT
{
    UPDATE_STATUS status;
    UINT error;
    LPCWSTR contentid;
}UPDATE_STATUS_REPORT;
HRESULT status([out] _UPDATE_STATUS_REPORT& pUpdateStatusReport) // Get status of current action

参数

参数	说明
pUpdateStatusReport	指向UPDATE_STATUS_REPORT结构的指针。

返回结果

结果	说明
S_OK	Status 方法始终返回此结果。检查 `UPDATE_STATUS_RESULT` 结构中当前操作的状态。

备注

的状态 UPDATE_STATUS_REPORT 字段包含当前操作的状态。返回以下状态值之一：

typedef enum _UPDATE_STATUS
{
eUPDATE_UNKNOWN = 0,
eDOWNLOAD_PENDING,
eDOWNLOAD_WIP,
eDOWNLOAD_CANCELLING,
eDOWNLOAD_CANCELLED,
eDOWNLOAD_FAILED,
eDOWNLOAD_SUCCEEDED,
eAPPLY_PENDING,
eAPPLY_WIP,
eAPPLY_SUCCEEDED,
eAPPLY_FAILED,
} UPDATE_STATUS;

如果最后一个命令导致错误，则的 UPDATE_STATUS_REPORT error 字段包含有关错误的详细信息。 从 Status 方法返回两种类型的错误代码。

如果错误小于 UPDATE_ERROR_CODE::eUNKNOWN，则错误是以下预定义错误代码之一：

typedef enum _UPDATE_ERROR_CODE
{
eOK = 0,
eFAILED_UNEXPECTED,
eTRIGGER_DISABLED,
ePIPELINE_IN_USE,
eFAILED_STOP_C2RSERVICE,
eFAILED_GET_CLIENTUPDATEFOLDER,
eFAILED_LOCK_PACKAGE_TO_UPDATE,
eFAILED_CREATE_STREAM_SESSION,
eFAILED_PUBLISH_WORKING_CONFIGURATION,
eFAILED_DOWNLOAD_UPGRADE_PACKAGE,
eFAILED_APPLY_UPGRADE_PACKAGE,
eFAILED_INITIALIZE_RSOD,
eFAILED_PUBLISH_RSOD,
// Keep this one as the last
eUNKNOWN
} UPDATE_ERROR_CODE;

如果返回错误代码大于 UPDATE_ERROR_CODE::eUNKNOWN 其为失败函数调用的 HRESULT 。从的错误字段中UPDATE_STATUS_REPORT返回的值中提取 HRESULTUPDATE_ERROR_CODE::eUNKNOWN。

可以通过检查嵌入在 OfficeC2RCom.dll 中的 IUpdateNotify 类型库来查看状态和错误值的完整列表。

contentid 字段用于在启动下载后调用 Status，并返回传入下载调用的 contentid。最佳做法是在调用 Status 方法之前将此字段初始化为 null，然后在返回 Status 后检查值。如果该值仍为 null，则表示没有要返回的 contentid。如果该值不为 null，则需要通过调用 SysFreeString 来释放它， () 。下面是有关如何在下载后调用 Status 的代码片段。
```
std::wstring contentID;
UPDATE_STATUS_REPORT statusReport;
statusReport.status = eUPDATE_UNKNOWN;
statusReport.error = eOK;
statusReport.contentid = NULL;
hr = p->Status(&statusReport);
if (statusReport.contentid != NULL)
{
contentID = statusReport.contentid;
SysFreeString(statusReport.contentid);
}
wprintf(L"ContentID: %s, Status: %d, LastError: %d", contentID.c_str(), statusReport.status, statusReport.error);
```

IUpdateNotify2 接口摘要

从版本 [16.0.8208.6352] 我们添加了一个新的 IUpdateNotify2 接口。

CLSID_UpdateNotifyObject2，{52C2F9C2-F1AC-4021-BF50-756A5FA8DDFE}
此接口还托管了原始 IUpdateNotify 接口，以提供向后兼容性。这意味着，如果使用此接口，则可以访问 UpdateNotifyObject 接口中提供的所有方法。
添加到 IUpdateNotify2 的新方法：
- HRESULT GetBlockingApps ([out] BSTR * AppsList) 。获取阻止应用列表的更新。此调用将返回正在运行的 Office 应用，这将阻止更新过程继续。
- HRESULT GetOfficeDeploymentData ([in] int dataType， [in] LPCWSTR pcwszName， [out] BSTR * OfficeData) 。获取 Office 部署数据。
如果要使用新方法，需要确保：
- C2R 版本比上述内部版本更新 (>= 6 月分叉生成) 。
- 使用 UpdateNotifyObject2 而不是 UpdateNotifyObject 调用 CoCreateInstance。

如果不使用任何新方法，则无需更改任何内容。所有现有方法的工作方式与之前完全相同。

实现 BITS 接口

后台智能传输服务 (BITS) 是 Microsoft 提供的用于在客户端和服务器之间传输文件的服务。 BITS 是 Office 即点即用安装程序可用于下载内容的通道之一。默认情况下，Microsoft 365 应用版即点即用安装程序使用 Windows 的 BITS 内置实现从 CDN 下载内容。

通过向 IUpdateNotify 接口的下载 () 方法提供自定义 BITS 实现，可管理性软件可以控制客户端下载内容的位置和方式。当提供即点即用内置通道以外的自定义内容分发通道（例如 CDN、IIS 服务器或文件共享）时，自定义 BITS 接口非常有用。

使用 Office C2R 服务的自定义 BITS 接口的最低要求是：

对于 IBackgroundCopyManager：

HRESULT _stdcall CreateJob(
                    [in] LPWSTR DisplayName, 
                    [in] BG_JOB_TYPE Type, 
                    [out] GUID* pJobId, 
                    [out] IBackgroundCopyJob** ppJob)
HRESULT _stdcall GetJob(
                    [in] GUID* jobID, 
                    [out] IBackgroundCopyJob** ppJob)
HRESULT _stdcall EnumJobs(
                    [in] unsigned long dwFlags, 
                    [out] IEnumBackgroundCopyJobs** ppenum)

对于 IBackgroundCopyJob：

HRESULT _stdcall AddFile(
                    [in] LPWSTR RemoteUrl, 
                    [in] LPWSTR LocalName)
HRESULT _stdcall Resume()
HRESULT _stdcall Complete()
HRESULT _stdcall Cancel();
HRESULT _stdcall GetState([out] BG_JOB_STATE* pVal);
HRESULT GetProgress( [out] BG_JOB_PROGRESS *pProgress);

对于 IBackgroundCopyJob3：

HRESULT _stdcall AddFileWithRanges(
                    [in] LPWSTR RemoteUrl, 
                    [in] LPWSTR LocalName,
                    [in] DWORD RangeCount,
                    [in] BG_FILE_RANGE Ranges[])

Addfile对于和 AddFileWithRanges 函数，远程 URL采用以下格式：
```
cmbits://<contentid>/<relative path to target file>
```
- cmbits 是硬编码的，代表自定义 BITS。
- <contentid> 是 Download () 方法的 contentid 参数。
- <目标文件的>相对路径提供要下载的文件的位置和文件名。
  
  例如，如果已向 Download () 方法提供了 contentidf732af58-5d86-4299-abe9-7595c35136ef，并且 Office C2R 想要下载版本 cab 文件（如 v32.cab file），它将使用以下RemoteUrl项调用 AddFile () ：
```
cmbits://f732af58-5d86-4299-abe9-7595c35136ef/Office/Data/V32.cab
```

对于 IBackgroundCopyError：

HRESULT _stdcall GetErrorDescription(
      [in]  DWORD  LanguageId,
      [out] LPWSTR *ppErrorDescription);

对于 IBackgroundCopyFile：

HRESULT _stdcall GetLocalName([out] LPWSTR *ppName); 
HRESULT _stdcall GetRemoteName([out] LPWSTR *ppName);

自动执行内容暂存

IT 管理员可以选择启用桌面客户端以在直接从 CDN 获取更新时自动接收更新，也可以选择使用 Office 部署工具或 Microsoft Endpoint Configuration Manager来控制更新通道中可用更新的部署。

该服务支持管理工具在更新可用时识别和自动下载内容的功能。

下图概述了如何下载自定义映像

在 Office 即点即用安装程序上使用 COM 界面的关系图。

下载自定义映像的概述

在上图中，可以看到 CDN 上提供了新的 Microsoft 365 应用版映像。除了Microsoft 365 应用版映像，还有一个 API，其中包含使可管理性软件直接创建自定义映像所需的信息，而无需使用 Office 部署工具。

企业将其 WSUS 配置为同步Microsoft 365 应用版更新。这些更新不包含实际的映像有效负载，但允许可管理性软件识别何时有新内容可用。然后，可管理性软件可以读取Microsoft 365 应用版更新元数据，以了解更新适用的 Office 版本。

如果更新适用，可管理性软件可以使用 CDN 内容和文件列表创建自定义映像，并将其存储在配置为使用的文件共享位置。

使用Microsoft 365 应用版文件列表 API

Microsoft 365 应用版文件列表 API 用于检索特定Microsoft 365 应用版更新所需的文件的名称。

HTTP 请求

获取 https://clients.config.office.net/releases/v1.0/filelist

请勿提供此方法的请求正文。

调用此 API 不需要任何权限。

可选的查询参数

名称	说明
通道	指定通道名称可选 - 默认为“半年” 支持的值 </DeployOffice/office-deployment-tool-configuration-options#channel-attribute-part-of-add-element.md>
version	指定更新版本可选 - 默认为指定通道可用的最新版本
拱	指定客户端体系结构可选 - 默认为“x64” 支持的值：x64、x86
盖子	指定要包含的语言文件可选 - 默认为无若要指定多种语言，请为每种语言包含一个 lid 查询参数使用语言标识符格式，例如 “en-us”、“fr-fr”
alllanguages	指定包含所有语言文件可选 - 默认为 false

HTTP 响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和文件对象的集合。

若要创建映像，请执行以下步骤：

调用 API，为感兴趣的更新的通道、版本和体系结构提供相应的查询参数。注意：属性为“lcid”：“0”的文件对象是非特定语言文件，必须包含在图像中。
通过循环访问文件对象并复制 CDN 文件来构造 CDN 的本地映像，同时创建由为每个文件对象定义的“relativePath”属性指定的文件夹结构。

以下示例检索当前频道的文件列表和 64 位版本 16.0.4229.1004，并包括法语和英语文件。

Get https://clients.config.office.net/releases/v1.0/filelist?Channel=Current&Version=16.0.4229.1004&Arch=x64&Lid=fr-fr&Lid=en-US

.dat文件的哈希验证

映像创建工具可以通过比较计算的哈希值与与每个.dat文件关联的提供的哈希值来验证下载.dat文件的完整性。下面是指定 hashLocation 和 hashAlgorithm 值的文件对象示例：

{
  "url": "https://officecdn.microsoft.com/pr/7ffbc6bf-bc32-4f92-8982-f9dd17fd3114/office/data/16.0.1234.1001/stream.x64.x-none.dat",
  "name": "stream.x64.x-none.dat",
  "relativePath": "/office/data/16.0.1234.1001/",
  "hashLocation": "s640.cab/stream.x64.x-none.hash",
  "hashAlgorithm": "Sha256",
  "lcid": "0"
},

hashLocation 属性指定包含哈希值的 .cab 文件的相对路径位置。通过连接 URL + relativePath + hashLocation 来构造哈希文件位置。在以下示例中，stream.x64.bg-bg.hash 位置将为：
```
https://officecdn.microsoft.com/pr/492350f6-3a01-4f97-b9c0-c7c6ddf67d60/office/data/16.0.4229.1004/s641026.cab/stream.x64.bg-bg.hash 
```
hashAlgorithm 属性指定使用了哪种哈希算法。

若要验证stream.x64.bg-bg.dat文件的完整性，请打开 stream.x64.bg-bg.hash 并读取 HASH 值，该值是哈希文件中的第一行文本。使用指定的哈希算法 () 将此与计算的哈希值进行比较，以验证下载的.dat文件的完整性。

以下示例演示用于读取哈希的 C# 代码。
```
  string[] readHashes = System.IO.File.ReadAllLines(tmpFile, Encoding.Unicode);
  string readHash = readHashes.First();
```

Microsoft 365 应用版汇报

所有Microsoft 365 应用版汇报都发布到 Microsoft 更新目录。

Microsoft 365 应用版汇报允许可管理性软件以与任何其他 WU 更新非常相似的方式处理Microsoft 365 应用版汇报，但有一个例外;客户端更新不包含实际有效负载。不应在任何客户端上安装Microsoft 365 应用版汇报，而应使用可管理性软件触发工作流，将安装命令替换为上面所示的基于 COM 的安装机制。

下图显示了Office 365客户端更新工作流的关系图。

O365PP 客户端更新的工作流图。

发布的每个Microsoft 365 应用版更新都包含有关更新的元数据。此元数据包括一个名为 MoreInfoUrl 的参数，该参数可用于派生针对该特定更新的文件列表 API 的 API 调用。

在以下示例中，文件列表 API 嵌入到 MoreInfoURL 中，以“ServicePath=”开头

https://go.microsoft.com/fwlink/?LinkId=626090&Ver=16.0.12527.21104&Branch=Insiders&Arch=64&XMLVer=1.6&xmlPath=http://officecdn.microsoft.com/pr/wsus/ofl.cab&xmlFile=O365Client_64bit.xml& ServicePath=https://go.microsoft.com/fwlink/?linkid=2190568&Channel=Insiders&Version=16.0.12527.21104&Arch=64&AllLanguages=True

用于自动执行内容暂存的其他元数据

发布发现 API

Microsoft 365 应用版发布发现 API 用于检索发布到 CDN 的每个更新的详细信息，以及通道名称和其他通道属性。

HTTP 请求

GET [https://clients.config.office.net/releases/v1.0/filelist/channels](https://clients.config.office.net/releases/v1.0/filelist/channels)

请勿提供此方法的请求正文。

调用此 API 不需要任何权限。

HTTP 响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和文件对象的集合。

SKU API

SKU API 返回的信息有助于确定哪些产品可从 Office CDN 进行部署和维护，以及每种产品的各种选项。

HTTP 请求

GET [https://clients.config.office.net/releases/v1.0/filelist/skus](https://clients.config.office.net/releases/v1.0/filelist/skus)

请勿提供此方法的请求正文。

调用此 API 不需要任何权限。

HTTP 响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和文件对象的集合。

通过

将可管理性应用程序与Microsoft 365 应用版即点即用安装程序集成

与即点即用集成

即点即用安装程序 COM API 参考指南

应用

参数

返回结果

备注

取消

返回结果

备注

下载

参数

返回结果

备注

示例

状态

参数

返回结果

备注

IUpdateNotify2 接口摘要

实现 BITS 接口

自动执行内容暂存

下载自定义映像的概述

使用Microsoft 365 应用版文件列表 API

.dat文件的哈希验证

Microsoft 365 应用版 汇报

用于自动执行内容暂存的其他元数据

反馈

其他资源

Microsoft 365 应用版汇报