Actualizar libro

Espacio de nombres: microsoft.graph.security

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Crear o reemplazar un libro con un identificador seleccionado por el cliente.

Proporcione un GUID en la dirección URL de la solicitud. Sin un encabezado condicional, este método crea el libro si ese identificador no existe o reemplaza su nombre y contenido si sí existe. Si se reutiliza el mismo GUID, se conserva la identidad del libro. Las novedades conservan createdByUpn y createdAtDateTime.

El valor de contenido reemplaza el documento JSON completo. No es una actualización parcial ni una combinación anidada.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet
✅ ❌ ❌ ❌

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Workbooks.ReadWrite.All No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Workbooks.ReadWrite.All No disponible.

El inquilino debe estar activo e incorporado para usar las API de Workbooks. Los permisos delegados de trabajo o escuela y aplicación requieren el consentimiento del administrador. El acceso delegado también requiere que el usuario que ha iniciado sesión tenga la autorización RBAC unificada de Microsoft Defender XDR aplicable. No se admiten cuentas personales de Microsoft.

Solicitud HTTP

PATCH /security/workbooks/{workbookId}

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.
Content-Type application/json. Obligatorio.
If-Match El libro actual ETag. Hace que la solicitud sea de solo actualización: el libro debe existir y la ETag debe coincidir. Opcional.
If-None-Match Establézcalo en * para que la solicitud sea una operación de solo creación atómica. El libro no debe existir ya. Opcional.

Para If-Match, copie el valor del encabezado de respuesta HTTP ETag del libro sin cambios, incluidos su W/ prefijo y comillas. Se aceptan representaciones fuertes y débiles de la ETag actual. Trate las ETags como valores opacos; no las genere usted mismo.

Cuerpo de la solicitud

Proporcione tanto el nombre como el contenido en el cuerpo de la solicitud. Incluya el documento de contenido completo; Las propiedades anidadas que omitas no se conservarán de la versión anterior.

Propiedad Tipo Descripción
contenido microsoft.graph.security.workbookContent El documento JSON completo que se va a almacenar. Proporciona un objeto JSON, no una cadena codificada en JSON.
name Cadena El nombre para mostrar del libro. La longitud máxima es de 256 caracteres.

No proporcione id., etag, createdByUpn, lastUpdatedByUpn, createdAtDateTime o updatedAtDateTime en el cuerpo de la solicitud. La dirección URL determina el ID; El servicio administra las propiedades de simultaneidad y auditoría.

Respuesta

Si se realiza correctamente, este método devuelve un objeto Microsoft.Graph.Security.Workbook en el cuerpo de la respuesta y uno de los siguientes códigos de respuesta:

  • 201 Created Cuándo se crea el libro. El Location encabezado contiene la dirección URL de Microsoft Graph del libro.
  • 200 OK Cuando se reemplaza un libro existente.

El ETag encabezado de respuesta contiene el token de simultaneidad actual del libro.

Errores

El método se devuelve 412 Precondition Failed cuando se cumple alguna de las condiciones siguientes:

  • Usted proporciona If-None-Match: *, pero el libro ya existe.
  • Usted proporciona If-Match, pero el libro no existe o la ETag proporcionada no coincide con su versión actual.

Ejemplos

Ejemplo 1: Reemplazar un libro solo si no ha cambiado

Solicitud

En el ejemplo siguiente se usa la información débil ETag devuelta por Obtener libro. El objeto de contenido suministrado reemplaza al 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."
      }
    ]
  }
}

Respuesta

En el ejemplo siguiente se muestra la respuesta. Se conservan las propiedades de auditoría de identificador y creación, mientras que las propiedades de auditoría de actualización y ETag reflejan la nueva versión. La propiedad content.settings anterior no se conserva porque no se proporcionó en el documento de reemplazo.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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"
}

Ejemplo 2: Crear un libro solo si su identificador no existe

Solicitud

En este ejemplo independiente se supone que el id. de libro no existe. El If-None-Match: * encabezado impide que la solicitud reemplace un libro que ya usa el 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
    }
  }
}

Respuesta

En el ejemplo siguiente se muestra la respuesta cuando el identificador no existía. Si se repite esta solicitud de solo creación después de que exista el libro, se devuelve .412 Precondition Failed

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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"
}
  • Se actualizó por última vez el