Compartilhar via

DeclaredConfiguration CSP

  • Artigo

Logótipo do Windows Insider.

Importante

Esse CSP contém algumas configurações que estão em desenvolvimento e só se aplicam Windows Insider Preview builds. Essas configurações estão sujeitas a alterações e podem ter dependências de outros recursos ou serviços em versão prévia.

O modelo mdm principal é aquele em que o servidor MDM é o único responsável pela orquestração e manutenção contínua do estado do dispositivo para cenários de configuração. Este comportamento resulta num tráfego de rede intensivo e numa latência de rede elevada devido ao modelo de configuração síncrono com base na norma OMA-DM Syncml. Também é propenso a erros, dado que o servidor precisa de um conhecimento profundo do cliente.

O modelo de gestão de dispositivos De configuração declarada do Windows (WinDC) requer que o servidor forneça todos os valores de definição ao dispositivo para a configuração do cenário. O servidor envia-os de forma assíncrona em lotes através do CSP DeclaredConfiguration.

  • Durante a sessão OMA-DM iniciada pelo cliente, o servidor WinDC envia uma configuração ou um documento WinDC de inventário para o cliente através do URI CSP DeclaredConfiguration. Se o dispositivo verificar se a sintaxe do documento está correta, a pilha de cliente envia o pedido ao orquestrador para processar o pedido de forma assíncrona. Em seguida, a pilha de cliente sai e devolve o controlo ao serviço WinDC. Este comportamento permite que o dispositivo processe o pedido de forma assíncrona.

  • No cliente, se existirem pedidos em curso ou concluídos, envia um alerta genérico para o servidor. Este alerta resume a status, o estado e o progresso de cada documento. Todos os pedidos HTTPS de cliente para o servidor OMA-DM WinDC incluem este resumo.

  • O servidor WinDC utiliza o alerta genérico para determinar que pedidos são concluídos com êxito ou com erros. Em seguida, o servidor pode obter de forma síncrona os resultados do processo do documento WinDC através do URI CSP DeclaredConfiguration.

A lista seguinte mostra os nós do fornecedor de serviços de configuração DeclaredConfiguration:

Host

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host

O nó interno do Anfitrião indica que o destino do pedido de configuração ou pedido de inventário é o SO anfitrião. Este nó destina-se ao âmbito no caso de os enclaves serem alguma vez direcionados para a configuração.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter

Anfitrião/Concluído

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete

Este nó interno indica que a configuração tem valores de definições discretos e é autónomo com pares de definições e valores completos que não contêm marcadores de posição que têm de ser resolvidos mais tarde com dados adicionais. O pedido está pronto para ser processado tal como está.

O fluxo do servidor para o cliente do pedido Complete é o mesmo que um pedido de Inventário .

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter

Anfitrião/Completo/Documentos

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents

O nó Documentos indica que a configuração está sob a forma de um documento, que é uma coleção de definições utilizadas para configurar um cenário pela pilha Configuração Declarada.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter
Anfitrião/Concluído/Documentos/{DocID}
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}

Identifica exclusivamente o documento de configuração. Nenhum outro documento pode ter este ID. O ID deve ser um GUID.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter
Nomenclatura de Nó Dinâmico ServerGeneratedUniqueIdentifier
Valores Permitidos Expressão Regular: [0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}
Anfitrião/Concluído/Documentos/{DocID}/Documento
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document

O valor do nó Documento é um documento baseado em XML que contém uma coleção de definições e valores para configurar o cenário especificado. A pilha Configuração Declarada verifica a sintaxe do documento, a pilha marca o documento a ser processado de forma assíncrona pelo cliente. Em seguida, a pilha devolve o controlo ao serviço OMA-DM. A pilha, por sua vez, processa de forma assíncrona o pedido. Segue-se um exemplo de uma configuração de estado pretendido especificada com o URI de Configuração Declarada ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Documento.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato chr (cadeia)
Tipo de acesso Adicionar, Excluir, Obter, Substituir
Anfitrião/Concluído/Documentos/{DocID}/Propriedades
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties

O nó Propriedades encapsula a lista de propriedades que se aplicam ao documento especificado referenciado por [DocID].

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter
Anfitrião/Completo/Documentos/{DocID}/Propriedades/Abandonado
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Properties/Abandoned

O nó Abandonado permite que o servidor OMA-DM indique que o documento já não é gerido.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato int
Tipo de acesso Adicionar, Excluir, Obter, Substituir
Valor Padrão 0

Valores Permitidos:

Valor Descrição
0 (Padrão) O documento já não é gerido.
1 O documento é gerido.

Anfitrião/Concluído/Resultados

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results

O nó Resultados indica que faz parte do caminho do URI que irá devolver um documento XML que contém os resultados do pedido de configuração.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Obter
Anfitrião/Concluído/Resultados/{DocID}
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}

Identifica exclusivamente o documento de configuração no qual os resultados do pedido de configuração serão devolvidos.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Obter
Nomenclatura de Nó Dinâmico ClientInventory
Anfitrião/Concluído/Resultados/{DocID}/Documento
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/{DocID}/Document

O valor do nó Documento é um documento baseado em XML que contém uma coleção de resultados de definição do pedido de configuração especificado por [DocId].

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato chr (cadeia)
Tipo de acesso Obter

Anfitrião/Inventário

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory

O nó interno Inventário indica que se trata de um pedido de inventário. Os valores de definição a obter são especificados num documento XML através do nó Folha do documento.

O fluxo do servidor para o cliente do pedido de Inventário é o mesmo que o pedido Concluído .

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter

Anfitrião/Inventário/Documentos

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents

O nó Documentos indica que o pedido de inventário está sob a forma de um documento, que é uma coleção de definições utilizadas para obter os respetivos valores.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter
Anfitrião/Inventário/Documentos/{DocID}
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}

Identifica exclusivamente o documento de inventário. Nenhum outro documento pode ter este ID. O ID deve ser um GUID.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Adicionar, Eliminar, Obter
Nomenclatura de Nó Dinâmico ServerGeneratedUniqueIdentifier
Valores Permitidos Expressão Regular: [0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}
Anfitrião/Inventário/Documentos/{DocID}/Documento
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/{DocID}/Document

O valor do nó Documento é um documento baseado em XML que contém uma coleção de definições que serão utilizadas para obter os respetivos valores. A pilha Configuração Declarada verifica a sintaxe do documento, a pilha marca o documento a ser processado de forma assíncrona pelo cliente. Em seguida, a pilha devolve o controlo ao serviço OMA-DM. A pilha, por sua vez, processa de forma assíncrona o pedido. Segue-se um exemplo de uma configuração de estado pretendido especificada com o URI de Configuração Declarada ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68. B9-4320-9. FC4-296. F6FDFAFE2/Documento.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato chr (cadeia)
Tipo de acesso Adicionar, Excluir, Obter, Substituir

Anfitrião/Inventário/Resultados

Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results

O nó Resultados indica que faz parte do caminho do URI que irá devolver um documento XML que contém os resultados do pedido de inventário.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Obter
Anfitrião/Inventário/Resultados/{DocID}
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}

Identifica exclusivamente o documento de inventário. Nenhum outro documento pode ter este ID. O ID deve ser um GUID.

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato node
Tipo de acesso Obter
Nomenclatura de Nó Dinâmico ClientInventory
Anfitrião/Inventário/Resultados/{DocID}/Documento
Escopo Edições Sistema operacional aplicável
Dispositivo ✅
Usuário ❌		 Pro ✅
Corporativo ✅
Educação ✅
Windows SE ✅
Empresa de Internet das Coisas / LTSC Empresa Internet das Coisas ✅		 ✅Windows Insider Preview 
./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Results/{DocID}/Document

O valor do nó Documento é um documento baseado em XML que contém uma coleção de resultados de definição do pedido de inventário especificado por [DocId].

Propriedades da estrutura de descrição:

Nome da propriedade Valor de propriedade
Formato chr (cadeia)
Tipo de acesso Obter

DeclaredConfiguration OMA URI

É enviado um pedido WinDC com um OMA-URI semelhante a ./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document.

  • O URI tem um prefixo com um âmbito de destino (User ou Device).
  • {DocID} é um identificador exclusivo para o estado pretendido do cenário de configuração. Cada documento tem de ter um ID, que tem de ser um GUID.
  • O pedido pode ser um Pedido de inventário ou completo .

O URI seguinte é um exemplo de um pedido Completo : ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document

Documento WinDC

<DeclaredConfiguration
    schema="1.0"
    context="Device"
    id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
    checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
    osdefinedscenario="MSFTExtensibilityMIProviderConfig">
    ... {Configuration Data} ...
</DeclaredConfiguration>

A <DeclaredConfiguration> etiqueta XML especifica os detalhes do documento WinDC a processar. O documento pode fazer parte de um pedido de configuração ou de um pedido de inventário. O CSP DeclaredConfiguration tem dois URIs para permitir a especificação de uma configuração ou um pedido de inventário .

Esta etiqueta tem os seguintes atributos:

Atributo Descrição
schema A versão de esquema do xml. Atualmente 1.0.
context Indica se o documento tem como destino o dispositivo ou o utilizador.
id O identificador exclusivo do documento definido pelo servidor. Este valor deve ser um GUID.
checksum Este valor é a versão fornecida pelo servidor do documento.
osdefinedscenario O cenário nomeado que o cliente deve configurar com os dados de configuração indicados.

O CSP DeclaredConfiguration valida de forma síncrona o lote de definições descrito pelo <DeclaredConfiguration> elemento, que representa o documento WinDC. Verifica a sintaxe correta com base no esquema XML WinDC. Se existir um erro de sintaxe, o CSP devolve imediatamente um erro ao servidor como parte da sessão OMA-DM atual. Se a sintaxe marcar for aprovada, o pedido é transmitido para um serviço Windows. O serviço Windows tenta de forma assíncrona a configuração de estado pretendido do cenário especificado. Este processo liberta o servidor para efetuar outros trabalhos, pelo que a baixa latência do protocolo WinDC. O serviço de cliente Do Windows, o orquestrador, é responsável por conduzir a configuração do dispositivo com base no estado pretendido fornecido pelo servidor. O serviço também mantém este estado ao longo da sua duração, até que o servidor o remova ou modifica.

O processamento real dos pivôs do pedido em torno da osdefinedscenario etiqueta e dos dados de configuração especificados no documento. Para obter mais informações, consulte:

Alerta genérico do WinDC

Em cada resposta do cliente ao pedido do servidor, o cliente cria um alerta WinDC. Este alerta resume o estado de cada um dos documentos que o serviço Windows processou. O seguinte XML é um alerta de exemplo:

<Alert>
  <CmdID>1</CmdID>
  <Data>1224</Data>
  <Item>
    <Meta>
      <Type xmlns="syncml:metinf">com.microsoft.mdm.declaredconfigurationdocuments</Type>
    </Meta>
    <Data>
      <DeclaredConfigurations schema="1.0">
        <DeclaredConfiguration context="Device"
                               id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
                               checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
                               result_checksum="EE4F1636201B0D39F71654427E420E625B9459EED17ACCEEE1AC9B358F4283FD"
                               state="60" />
      </DeclaredConfigurations>
    </Data>
  </Item>
</Alert>

Neste exemplo, existe um documento WinDC listado no resumo do alerta. O resumo do alerta lista todos os documentos que a pilha de cliente está a processar, quer seja um pedido de configuração ou inventário. Descreve o contexto do documento que especifica o âmbito da aplicação do documento. O valor de contexto deve ser Device.

O atributo state tem um valor de 60, que indica que o documento foi processado com êxito.

Estados do WinDC

A classe seguinte define os valores de estado:

enum class DCCSPURIState :unsigned long
{
    NotDefined = 0, // transient
    ConfigRequest = 1, // transient
    ConfigInprogress = 2, // transient
    ConfigInProgressAsyncPending = 3, // transient: Async operation is performed but pending results
    DeleteRequest = 10,  // transient
    DeleteInprogress = 11,  // transient

    GetRequest = 20,  // transient
    GetInprogress = 21,  // transient

    ConstructURIStorageSuccess = 40, // transient

    ConfigCompletedSuccess = 60, // permanent
    ConfigCompletedError = 61, // permanent
    ConfigInfraError = 62, // permanent
    ConfigCompletedSuccessNoRefresh = 63, // permanent

    DeleteCompletedSuccess = 70, // permanent
    DeleteCompletedError = 71, // permanent
    DeleteInfraError = 72, // permanent

    GetCompletedSuccess = 80, // permanent
    GetCompletedError = 81, // permanent
    GetInfraError = 82 // permanent
};

Exemplos de SyncML

Abandonar um documento WinDC

O abandono de um recurso ocorre quando determinados recursos já não são direcionados para um utilizador ou grupo. Em vez de eliminar o recurso no dispositivo, o servidor pode optar por abandonar o documento WinDC. Um recurso abandonado permanece no dispositivo, mas deixa de atualizar o documento WinDC que processa o controlo de desfasamento. Além disso, a propriedade do recurso é transferida para a MDM, o que significa que o mesmo recurso pode ser modificado novamente através do canal MDM legado.

Este exemplo demonstra como abandonar um documento WinDC ao definir a propriedade Abandonada como 1.

<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
    <CmdID>2</CmdID>
    <Item>
        <Meta>
            <Format>int</Format>
            <Type>text/plain</Type>
        </Meta>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned</LocURI>
        </Target>
        <Data>1</Data>
    </Item>
    </Replace>
    <Final/>
  </SyncBody>
</SyncML>

Anular a banda num documento WinDC

A anulação do documento faz com que o documento seja aplicado imediatamente, transferindo a propriedade do recurso de volta para a gestão do WinDC e impedindo o canal mdm legado de gerir novamente os canais.

Este exemplo demonstra como remover um documento WinDC ao definir a propriedade Abandonada como 0.

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>10</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
        </Target>
        <Meta>
          <Format xmlns="syncml:metinf">int</Format>
        </Meta>
        <Data>0</Data>
      </Item>
    </Replace>
    <Final />
  </SyncBody>
</SyncML>

Eliminar um documento WinDC

A eliminação de SyncML do documento só remove o documento, mas as definições persistem no dispositivo. Este exemplo demonstra como eliminar um documento.

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
    <Delete>
        <CmdID>2</CmdID>
        <Item>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        </Item>
    </Delete>
    <Final/>
    </SyncBody>
</SyncML>

Referência de provedor de serviços de configuração