Atualizar pasta de trabalho

Namespace: microsoft.graph.security

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie ou substitua uma pasta de trabalho usando uma ID selecionada pelo cliente.

Forneça um GUID na URL da solicitação. Sem um cabeçalho condicional, esse método cria a pasta de trabalho se essa ID não existir ou substitui seu nome e conteúdo se existir. A reutilização do mesmo GUID preserva a identidade da pasta de trabalho. Atualizações preservam createdByUpn e createdAtDateTime.

O valor de conteúdo substitui o documento JSON completo. Não é uma atualização parcial ou uma mesclagem aninhada.

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) Workbooks.ReadWrite.All Indisponível.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Workbooks.ReadWrite.All Indisponível.

O locatário deve estar ativo e integrado para usar as APIs de Pastas de Trabalho. As permissões delegadas de trabalho ou escola e aplicativo exigem o consentimento do administrador. O acesso delegado também exige que o usuário conectado tenha a autorização RBAC Unificada aplicável do Microsoft Defender XDR. Não há suporte para contas Microsoft pessoais.

Solicitação HTTP

PATCH /security/workbooks/{workbookId}

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.
If-Match A pasta de trabalho atual ETag. Torna a solicitação somente atualização: a pasta de trabalho deve existir e a ETag deve corresponder. Opcional.
If-None-Match Defina como * para tornar a solicitação uma operação atômica somente de criação. A pasta de trabalho ainda não deve existir. Opcional.

Para If-Match, copie o valor do cabeçalho de resposta HTTP ETag da pasta de trabalho inalterado, incluindo seu W/ prefixo e aspas. Representações fortes e fracas correspondentes da ETag atual são aceitas. Tratar as ETags como valores opacos; não as gere por conta própria.

Corpo da solicitação

Forneça o nome e o conteúdo no corpo da solicitação. Inclua o documento de conteúdo completo; As propriedades aninhadas que você omite não são retidas da versão anterior.

Propriedade Tipo Descrição
conteúdo microsoft.graph.security.workbookContent O documento JSON completo a ser armazenado. Forneça um objeto JSON, não uma cadeia de caracteres codificada em JSON.
nome Cadeia de caracteres O nome de exibição da pasta de trabalho. O comprimento máximo é de 256 caracteres.

Não forneça id, etag, createdByUpn, lastUpdatedByUpn, createdAtDateTime ou updatedAtDateTime no corpo da solicitação. A URL determina o ID; O serviço gerencia as propriedades de simultaneidade e auditoria.

Resposta

Se for bem-sucedido, esse método retornará um objeto microsoft.graph.security.workbook no corpo da resposta e um dos seguintes códigos de resposta:

  • 201 Created quando a pasta de trabalho é criada. O Location cabeçalho contém a URL do Microsoft Graph da pasta de trabalho.
  • 200 OK quando uma pasta de trabalho existente é substituída.

O ETag cabeçalho de resposta contém o token de simultaneidade atual da pasta de trabalho.

Erros

O método retorna 412 Precondition Failed quando uma das seguintes condições se aplica:

  • Você fornece If-None-Match: *, mas a pasta de trabalho já existe.
  • Você fornece If-Match, mas a pasta de trabalho não existe ou a ETag fornecida não corresponde à versão atual.

Exemplos

Exemplo 1: Substituir uma pasta de trabalho somente se ela não tiver sido alterada

Solicitação

O exemplo a seguir usa o weak ETag retornado pela pasta de trabalho Get. O objeto de conteúdo fornecido substitui o documento anterior.

PATCH https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
Content-Type: application/json
If-Match: W/"0x8DE000000000001"

{
  "name": "Threat hunting overview - updated",
  "content": {
    "version": "2.0",
    "title": "Priority investigations",
    "items": [
      {
        "type": "text",
        "text": "Review the highest-priority investigations first."
      }
    ]
  }
}

Resposta

O exemplo a seguir mostra a resposta. A ID e as propriedades de auditoria de criação são preservadas, enquanto as propriedades de auditoria de atualização e ETag refletem a nova versão. A propriedade content.settings anterior não é mantida porque não foi fornecida no documento de substituição.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-Type: application/json
ETag: W/"0x8DE000000000002"

{
  "@odata.type": "#microsoft.graph.security.workbook",
  "id": "ba989c62-af63-b8de-286d-7474ec579357",
  "name": "Threat hunting overview - updated",
  "content": {
    "version": "2.0",
    "title": "Priority investigations",
    "items": [
      {
        "type": "text",
        "text": "Review the highest-priority investigations first."
      }
    ]
  },
  "createdByUpn": "adelev@contoso.com",
  "lastUpdatedByUpn": "alexw@contoso.com",
  "createdAtDateTime": "2026-09-22T10:00:00Z",
  "updatedAtDateTime": "2026-09-22T10:15:00Z"
}

Exemplo 2: Criar uma pasta de trabalho somente se sua ID não existir

Solicitação

Este exemplo independente pressupõe que a ID da pasta de trabalho não existe. O If-None-Match: * cabeçalho impede que a solicitação substitua uma pasta de trabalho que já usa a ID.

PATCH https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
Content-Type: application/json
If-None-Match: *

{
  "name": "Threat hunting overview",
  "content": {
    "version": "1.0",
    "title": "Threat hunting overview",
    "items": [
      {
        "type": "text",
        "text": "Investigate recent security activity."
      }
    ],
    "settings": {
      "showTitle": true
    }
  }
}

Resposta

O exemplo a seguir mostra a resposta quando a ID não existia. Repetir essa solicitação somente de criação após a existência da pasta de trabalho retorna 412 Precondition Failed.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://graph.microsoft.com/beta/security/workbooks/ba989c62-af63-b8de-286d-7474ec579357
ETag: W/"0x8DE000000000001"

{
  "@odata.type": "#microsoft.graph.security.workbook",
  "id": "ba989c62-af63-b8de-286d-7474ec579357",
  "name": "Threat hunting overview",
  "content": {
    "version": "1.0",
    "title": "Threat hunting overview",
    "items": [
      {
        "type": "text",
        "text": "Investigate recent security activity."
      }
    ],
    "settings": {
      "showTitle": true
    }
  },
  "createdByUpn": "adelev@contoso.com",
  "lastUpdatedByUpn": "adelev@contoso.com",
  "createdAtDateTime": "2026-09-22T10:00:00Z",
  "updatedAtDateTime": "2026-09-22T10:00:00Z"
}
  • Última atualização em