整合管理性應用程式與 Microsoft 365 Apps 隨選即用安裝程式
瞭解如何整合 Microsoft 365 Apps 隨選即用安裝程式與軟體管理解決方案。
Microsoft 365 Apps 隨選即用安裝程式提供 COM 介面,可讓 IT 專業人員和軟體管理解決方案以程式設計方式控制更新管理。 此介面提供 Office 部署工具所提供的額外管理功能。
注意事項
本文適用於使用隨選即用安裝程式的 Office 應用程式。
與隨選即用整合
若要使用此介面,可管理性應用程式會叫用 COM 介面,並呼叫公開的 API,直接與隨選即用安裝服務通訊。
注意事項
Office 隨選即用安裝程式可以使用可控制行為的參數從命令行執行,如隨選即用 Office 部署工具中所述。
以下是 COM 介面的概念圖表
Microsoft 365 Apps 隨選即用安裝程式會實作以 COM 為基礎的介面,IUpdateNotify 已註冊至 CLSID CLSID_UpdateNotifyObject。
此介面的叫用方式如下:
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 介面狀態機器圖表
注意事項
重新啟動:當計算機開機時,有一段時間無法使用隨選即用安裝程序服務。 重新啟動之後成功呼叫 Status 方法會傳回eUPDATE_UNKNOWN。
閑置: 當隨選即用安裝程式處於閑置狀態時,您可以呼叫:
套用:安裝先前下載的內容。
取消:傳回
0x800000e
「在非預期的時間呼叫方法」。下載:將新內容下載到用戶端以供稍後安裝。
狀態:傳回上次完成動作的結果,如果動作以失敗結束,則傳回錯誤訊息。 如果沒有先前的動作, Status 會傳回
eUPDATE_UNKNOWN
。
下載: 當隨選即用安裝程式處於下載狀態時,您可以呼叫:
套用:傳回 HRESULT ,其值
0x800000e
為「在非預期的時間呼叫方法」。取消:停止下載並移除部分下載的內容。
下載:傳回 HRESULT ,其值
0x800000e
為「在非預期的時間呼叫方法」。狀態:傳回 DOWNLOAD_WIP ,表示下載工作正在進行中。
應用: 當隨選即用安裝程式正在安裝先前下載的內容時:
套用:傳回 HRESULT ,其值
0x800000e
為「在非預期的時間呼叫方法」。取消:傳回
0x800000e
,無法取消 [套用] 動作。下載:傳回 HRESULT ,其值
0x800000e
為「在非預期的時間呼叫方法」。狀態:傳回 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 應用程式立即關閉; false 表示在執行任何 Office 應用程式時失敗。 預設值為 false 。 See Remarks for more information.
如果觸發 [ 套 用] 動作時有任何 Office 應用程式正在執行,[ 套用 ] 動作通常會失敗。 傳遞
forceappshutdown=true
至 Apply 方法會導致 OfficeClickToRun 服務立即關閉應用程式並套用更新。 在此情況下,使用者可能會遇到數據遺失。
傳回結果
結果 | 描述 |
---|---|
S_OK |
動作已成功提交至隨選即用服務以供執行。 |
E_ACCESSDENIED |
呼叫端未以較高的許可權執行。 |
E_INVALIDARG |
傳遞的參數無效。 |
E_ILLEGAL_METHOD_CALL |
目前不允許採取動作。 See Remarks for more information. |
註解
如果觸發 [ 套 用] 動作時有任何 Office 應用程式正在執行,[ 套用 ] 動作將會失敗。 傳遞
forceappshutdown=true
至 Apply 方法會導致 OfficeClickToRun 服務立即關閉任何執行中的 Office 應用程式並套用更新。 使用者可能會遇到數據,因為系統不會提示他們儲存變更以開啟檔。。只有當 COM 狀態為下列其中一項時,才能觸發此動作:
eUPDATE_UNKNOWN
eDOWNLOAD_CANCELLED
eDOWNLOAD_FAILED
eDOWNLOAD_SUCCEEDED
eAPPLY_SUCCEEDED
eAPPLY_FAILED
如果您在先前未下載內容的情況下呼叫 Apply 方法, Apply 方法會報告 Succeeded ,因為它偵測到沒有套用專案,並成功完成 套用 程式。
取消
HRESULT Cancel() // Cancel the download action.
傳回結果
結果 | 描述 |
---|---|
S_OK |
動作已成功提交至隨選即用服務以供執行。 |
E_ILLEGAL_METHOD_CALL |
目前不允許採取動作。 See the Remarks section for more information |
註解
- 只有當 COM 狀態標識 碼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 管理員) 。
- contentid:識別要透過自定義 BITS 管理員從內容伺服器下載的內容。 這個值會透過 BITS 介面傳遞以進行解譯。
傳回結果
結果 | 描述 |
---|---|
S_OK |
動作已成功提交至隨選即用服務以供執行。 |
E_ACCESSDENIED |
呼叫端未以較高的許可權執行。 |
E_INVALIDARG |
傳遞的參數無效。 |
E_ILLEGAL_METHOD_CALL |
目前不允許採取動作。 See Remarks for more information. |
註解
您必須將 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 參數。
若要從自訂位置下載內容:呼叫 下載 () 函式傳遞下列參數:
"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
會包含錯誤的詳細資訊。 從 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
中傳回的值中擷取 HRESULT 減UPDATE_ERROR_CODE::eUNKNOWN
去。檢查內嵌在 OfficeC2RCom.dll 中的 IUpdateNotify 類型連結庫,即可檢視狀態和錯誤值的完整清單。
contentid 欄位用於在 Download 起始之後呼叫 Status,並傳回傳入下載呼叫的 contentid。 最佳做法是在呼叫 Status 方法之前,先將此字段初始化為 null,然後在傳回 Status 之後檢查值。 如果值仍為 null,表示沒有 contentid 可傳回。 如果值不是 Null,您必須呼叫 SysFreeString () 來釋放它。 以下是如何在下載後呼叫狀態的代碼段。
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 Apps 隨選即用安裝程式會使用 Windows 內建的 BITS 實作,從 CDN 下載內容。
藉由提供自定義的 BITS 實作給 IUpdateNotify 介面的下載 () 方法,您的管理性軟體可以控制用戶端下載內容的位置和方式。 自定義 BITS 介面在提供隨選即用內建通道以外的自定義內容發佈通道時很有用,例如 CDN、IIS 伺服器或檔案共用。
自定義 BITS 介面使用 Office C2R 服務的最低需求是:
針對 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>
cmbit 是硬式編碼,代表自定義的BITS。
<contentid> 是 Download () 方法的 contentid 參數。
<目標檔案>的相對路徑提供要下載之檔案的位置和檔名。
例如,如果您已將 的
f732af58-5d86-4299-abe9-7595c35136ef
contentid 提供給 Download () 方法,而 Office C2R 想要下載版本 cab 檔案,例如v32.cab
檔案,它會呼叫 AddFile () ,並包含下列專案RemoteUrl
:
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 端點 Configuration Manager 來控制更新通道中可用更新的部署。
此服務支援管理工具在更新可供使用時辨識及自動下載內容的能力。
下圖是下載自定義映像的概觀
下載自定義映像的概觀
在上圖中,您會看到CDN上有新的 Microsoft 365 Apps 映像可供使用。 除了 Microsoft 365 Apps 映射,也提供 API,其中包含啟用管理性軟體以直接建立自定義映像所需的資訊,以取代使用 Office 部署工具的需求。
企業會將其 WSUS 設定為同步處理 Microsoft 365 Apps 更新。 這些更新不包含實際的映射承載,但可讓管理性軟體辨識新內容何時可用。 接著,管理性軟體可以閱讀 Microsoft 365 Apps Update 元數據,以瞭解更新適用的 Office 版本。
如果更新適用,管理性軟體可以使用CDN內容和檔案清單來建立自定義映像,並將它儲存到設定為使用的檔案共用位置。
使用 Microsoft 365 Apps 檔案清單 API
Microsoft 365 Apps 檔案清單 API 可用來擷取特定 Microsoft 365 Apps 更新所需的檔案名稱。
HTTP 要求
獲取 https://clients.config.office.net/releases/v1.0/filelist
請勿提供這個方法的要求本文。
呼叫此 API 不需要任何許可權。
選擇性查詢參數
名稱 | 描述 |
---|---|
通道 |
指定通道名稱 選擇性 – 預設為 'SemiAnnual' 支援的值 </DeployOffice/office-deployment-tool-configuration-options#channel-attribute-part-of-add-element.md> |
版本 |
指定更新版本 選擇性 – 預設為指定通道可用的最新版本 |
拱 |
指定客戶端架構 選擇性 – 預設為 'x64' 支援的值:x64、x86 |
lid |
指定要包含的語言檔案 選擇性 – 預設為無 若要指定多種語言,請針對每種語言包含 Lid 查詢參數 使用語言識別碼格式,例如 'en-us', 'fr-fr' |
alllanguages |
指定要包含所有語言檔案 選擇性 – 預設為 false |
HTTP 回應
如果成功,這個方法會傳回響應主體中 200 OK 回應碼和檔案物件的集合。
若要建立映像,請遵循下列步驟:
- 呼叫 API,為您感興趣之更新的通道、版本和架構提供適當的查詢參數。 注意:屬性為 「lcid」 : “0” 的檔案對像是語言中性檔案,必須包含在影像中。
- 逐一查看檔案物件並複製CDN檔案,同時建立每個檔案物件定義的 「relativePath」 屬性所指定的資料夾結構,以建構CDN的本機映像。
下列範例會擷取目前通道的檔案清單和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 Apps 匯報
所有 Microsoft 365 Apps 匯報 都會發佈至 Microsoft Update Catalog。
Microsoft 365 Apps 匯報 啟用管理性軟體,以非常類似於任何其他 WU 更新的方式來處理 Microsoft 365 Apps 匯報,但其中一個例外;用戶端更新不包含實際的承載。 Microsoft 365 Apps 匯報 不應該安裝在任何用戶端上,而是用來使用管理性軟體觸發工作流程,並將安裝命令取代為上述以 COM 為基礎的安裝機制。
下圖顯示 Office 365 用戶端更新工作流程的圖表。
發行的每個 Microsoft 365 Apps 更新都包含有關更新的元數據。 此元數據包含稱為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 Apps 發行探索 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 回應碼和檔案物件的集合。