共用方式為

NetProvisionComputerAccount 函式 (lmjoin.h)

  • 發行項

NetProvisionComputerAccount 函式會布建計算機帳戶，以供稍後在離線網域加入作業中使用。

語法

NET_API_STATUS NET_API_FUNCTION NetProvisionComputerAccount(
  [in]            LPCWSTR lpDomain,
  [in]            LPCWSTR lpMachineName,
  [in, optional]  LPCWSTR lpMachineAccountOU,
  [in, optional]  LPCWSTR lpDcName,
  [in]            DWORD   dwOptions,
  [out, optional] PBYTE   *pProvisionBinData,
  [out, optional] DWORD   *pdwProvisionBinDataSize,
  [out, optional] LPWSTR  *pProvisionTextData
);

參數

[in] lpDomain

NULL 終止字元字串的指標，指定建立計算機帳戶之網域的名稱。

[in] lpMachineName

NULL 終止字元字串的指標，指定計算機帳戶屬性 sAMAccountName 衍生來源之計算機的簡短名稱，方法是附加 『$』。 此參數必須包含有效的 DNS 或 NetBIOS 機器名稱。

[in, optional] lpMachineAccountOU

NULL 終止字元字串的選擇性指標，其中包含將建立計算機帳戶之組織單位的 RFC 1779 格式名稱 (OU) 。 如果您指定此參數，字串必須包含完整路徑，例如 OU=testOU，DC=domain，DC=Domain，DC=com。 否則，此參數必須是 NULL。

如果此參數為 NULL，則已知計算機物件容器將作為在網域中發佈。

[in, optional] lpDcName

NULL 終止字元字串的選擇性指標，其中包含要設為目標的域控制器名稱。

[in] dwOptions

定義布建選項的一組位旗標。 此參數可以是 Lmjoin.h 頭檔中定義的下列一或多個值。

值 意義
NETSETUP_PROVISION_DOWNLEVEL_PRIV_SUPPORT
0x00000001
 如果呼叫端需要以許可權建立帳戶，此選項將會使用帳戶建立函式來重試失敗，以便與在舊版 Windows 上執行的域控制器互通。

使用下層許可權支援時，不支援 lpMachineAccountOU 。
NETSETUP_PROVISION_REUSE_ACCOUNT
0x00000002
 如果具名帳戶已經存在，將會嘗試重複使用現有的帳戶。

此選項需要足夠的認證，才能進行這項作業， (網域管理員或對象擁有者) 。
NETSETUP_PROVISION_USE_DEFAULT_PASSWORD
0x00000004
 使用預設電腦帳戶密碼，這是小寫的計算機名稱。 這主要是為了支援較舊的不安全聯結模型，其中預先建立的帳戶通常會使用此默認密碼。
注意 如果可能的話，應用程式應該避免使用此選項。 此選項以及具有 dwOptions 的 NetJoinDomain 函式設定為 NETSETUP_JOIN_UNSECURE 以進行不安全的聯結，應該只在舊版 Windows 上使用。
 
NETSETUP_PROVISION_SKIP_ACCOUNT_SEARCH
0x00000008
 請勿嘗試在網域中的任何域控制器上尋找帳戶。 此選項可讓作業更快速，但只有在呼叫端確定最近尚未建立相同名稱的帳戶時使用。

只有在指定 lpDcName 參數時，此選項才有效。 當符合必要條件時，此選項可讓布建更快速，適用於批處理等案例。
NETSETUP_PROVISION_ROOT_CA_CERTS
0x00000010
 此選項會擷取本機計算機上的所有跟證書授權單位憑證，並在未提供任何證書範本名稱作為布建套件的一部分時新增至布建套件， (pProvisioningParams 參數中傳遞至 NetCreateProvisioningPackage 函式的 aCertTemplateNamesNETSETUP_PROVISIONING_PARAMS 成員為 NULL) 。
注意只有 netCreateProvisioningPackage 函式支援此旗標，Windows 8、Windows Server 2012 及更新版本。
 

[out, optional] pProvisionBinData

選擇性指標，如果 NetProvisionComputerAccount 函式成功完成，則會接收 NetRequestOfflineDomainJoin 函式所需的不透明二進位元數據 Blob，以完成離線網域聯結。 數據會以不透明二進位緩衝區的形式傳回，此緩衝區可能會傳遞至 NetRequestOfflineDomainJoin 函式。

如果此參數為 NULL， 則 pProvisionTextData 參數不得為 NULL。 如果此參數不是 NULL， 則 pProvisionTextData 參數必須是 NULL。

[out, optional] pdwProvisionBinDataSize

值的指標，這個值會接收 pProvisionBinData 參數中傳回之緩衝區的大小，以位元組為單位。

如果 pProvisionBinData 參數不是 NULL，這個參數不得為 NULL。 當 pProvisionBinData 參數為 NULL 時，此參數必須是 NULL。

[out, optional] pProvisionTextData

選擇性指標，如果 NetProvisionComputerAccount 函式成功完成，則會接收 NetRequestOfflineDomainJoin 函式所需的不透明二進位元數據 Blob，以完成離線網域聯結。 數據會以字串形式傳回，以便內嵌在自動安裝響應檔案中。

如果此參數為 NULL， 則 pProvisionBinData 參數不得為 NULL。 如果此參數不是 NULL， 則 pProvisionBinData 參數必須是 NULL。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼或其中一個 系統錯誤碼。

傳回碼 Description
ERROR_ACCESS_DENIED
 存取遭到拒絕。 如果呼叫端沒有足夠的許可權來完成作業，就會傳回此錯誤。
ERROR_INVALID_DOMAIN_ROLE
 此作業僅適用於網域的主要域控制器。 如果在 lpDcName 參數中指定域控制器名稱，但指定的電腦無法驗證為 lpDomain 參數中所指定目標網域的域控制器，就會傳回此錯誤。
ERROR_INVALID_PARAMETER
 參數不正確。 如果 lpDomain 或 lpMachineName 參數為 NULL，就會傳回此錯誤。 如果 pProvisionBinData 和 pProvisionTextData 參數都是 NULL，也會傳回此錯誤。
ERROR_NO_SUCH_DOMAIN
 指定的網域不存在。
ERROR_NOT_SUPPORTED
 不支援此要求。 如果指定 了 lpMachineAccountOU 參數，且域控制器正在不支援此參數的舊版 Windows 上執行，就會傳回此錯誤。
NERR_DS8DCRequired
 指定的域控制器不符合此作業的版本需求。
NERR_LDAPCapableDCRequired
 這項作業需要支援LDAP的域控制器。
NERR_UserExists
 帳戶已存在於網域中，且 dwOptions 參數中未指定NETSETUP_PROVISION_REUSE_ACCOUNT位。
NERR_WkstaNotStarted
 工作站服務尚未啟動。
RPC_S_CALL_IN_PROGRESS
 此線程已經在進行遠端過程調用。
RPC_S_PROTSEQ_NOT_SUPPORTED
 不支援遠端過程調用通訊協定序列。

備註

Windows 7 和 Windows Server 2008 R2 支援 NetProvisionComputerAccount 函式，以進行脫機聯結作業。 在 Windows 8 或 Windows Server 2008 R2 上，建議使用 NetCreateProvisioningPackage 函式，而不是 NetProvisionComputerAccount 函式。

NetProvisionComputerAccount 函式可用來布建計算機帳戶，以便稍後使用 NetRequestOfflineDomainJoin 函式在離線網域加入作業中使用。 離線網域加入案例會使用這些函式，如下所示：

  • NetProvisionComputerAccount 是布建函式，會先呼叫以執行在 Active Directory 中建立和設定計算機物件所需的網路作業。 NetProvisionComputerAccount 的輸出是用於下一個步驟之串行化元數據的不透明二進位 Blob。
  • 接著會呼叫 NetRequestOfflineDomainJoin，將 NetProvisionComputerAccount 布建函式的輸出插入 Windows 作業系統映像，以在安裝期間使用。
Windows 初始化程式代碼的變更會偵測到此已儲存的狀態，並影響加入網域的本機部分。

NetProvisionComputerAccount 函式會在網域中建立或重複使用計算機帳戶、收集所有必要的元數據，並在不透明版本的二進位 Blob 中傳回它，或當做自動安裝響應檔案中內嵌的文字傳回。 離線網域加入要求作業可取用不透明的二進位 Blob，提供第一次開機期間完成網域加入的所有必要輸入，而不需要任何網路作業 (本機狀態更新) 。

安全性注意事項： NetProvisionComputerAccount 函式所傳回的 Blob 包含非常敏感的數據。 它應該安全地視為純文本密碼。 Blob 包含計算機帳戶密碼和其他網域的相關信息，包括功能變數名稱、域控制器的名稱，以及網域的安全性標識碼 (SID) 。 如果 Blob 是以實體方式或透過網路傳輸，則必須小心安全地傳輸它。 設計不會布建保護此數據。 此問題目前有自動安裝回應檔案存在，這些檔案可以包含一些秘密，包括網域用戶密碼。 呼叫端必須保護 Blob 和自動安裝檔案。 此問題的解決方案會有所不同。 例如，預先交換的密鑰可用來加密取用者與布建實體之間的會話，以安全傳輸不透明 Blob。

NetProvisionComputerAccount 函式在 pProvisionBinData 參數中傳回的不透明 Blob 會建立版本，以允許不同 Windows (聯結用戶端、布建計算機和域控制器) 之間的互操作性和服務性案例。 離線聯結案例目前不會限制 NetProvisionComputerAccount 函式所傳回之 Blob 的存留期。

針對離線網域加入，執行的存取檢查取決於網域的設定。 使用三種方法開啟電腦帳戶建立：

  • 網域系統管理員有權建立計算機帳戶。
  • 容器上的 SD 可以委派建立電腦帳戶的許可權。
  • 根據預設，已驗證的使用者可能會依許可權建立計算機帳戶。 已驗證的使用者僅限於建立在網域上指定為配額的有限帳戶數目， (預設值為10) 。 如需詳細資訊，請參閱 Active Directory 架構中的 ms-DS-MachineAccountQuota 屬性。

NetProvisionComputerAccount 函式只適用於可寫入的域控制器，而且不適用於唯讀域控制器。 一旦針對可寫入的域控制器進行布建，且帳戶會復寫至只讀域控制器，則脫機網域加入作業的其他部分不需要存取域控制器。

如果 NetProvisionComputerAccount 函式成功，則 pProvisionBinData 或 pProvisionTextData 參數中的指標 (取決於參數不是 NULL) 會隨著串行化數據傳回，以便用於脫機聯結作業或自動安裝檔案中的文字。

如需脫機網域加入作業的詳細資訊，請參閱 脫機網域加入逐步指南。

使用 NetJoinDomain 和 NetUnjoinDomain 將電腦加入網域 (和取消加入) 只能由目標電腦上的 Administrators 本地組成員執行。 請注意，網域系統管理員可以使用委派和指派許可權來設定加入網域的其他需求。

規格需求

   
最低支援的用戶端 Windows 7 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限桌面應用程式]
目標平台 Windows
標頭 lmjoin.h (包含 Lm.h)
程式庫 Netapi32.lib
Dll Netapi32.dll

另請參閱

NetCreateProvisioningPackage

NetJoinDomain

NetRenameMachineInDomain

NetRequestOfflineDomainJoin

NetUnjoinDomain

網路管理功能

網路管理概觀

離線網域加入逐步指南

ms-DS-MachineAccountQuota