Recuperar datos de conexión a tierra

Importante

Las API de la /beta versión están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción.

La API de recuperación de Microsoft 365 Copilot recupera extractos de texto relevantes del contenido de los conectores de SharePoint, OneDrive y Copilot. La seguridad de API recorta el contenido para el usuario que llama y respeta los controles de acceso definidos dentro del espacio empresarial. Use la API de recuperación para fundamentar sus soluciones de IA generativa con datos de Microsoft 365 mientras optimiza para la recuperación de contexto.

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) Files. Read.All, Sites.Read.All* ExternalItem.Read.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación No admitida. No admitida.

* Para recuperar contenido de SharePoint y OneDrive, necesita ambos Files. Permisos Read.All y Sites.Read.All.

Solicitud HTTP

POST https://graph.microsoft.com/beta/copilot/retrieval

POST https://graph.microsoft.com/v1.0/copilot/retrieval

Encabezados de solicitud

Nombre Descripción
Authorization Bearer {token}. Obligatorio. Obtenga más información sobre autenticación y autorización.
Content-Type application/json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de los parámetros.

En la tabla siguiente se enumeran los parámetros opcionales y necesarios que puede utilizar al llamar a esta acción.

Parámetro Tipo Descripción
queryString Cadena Cadena de consulta en lenguaje natural usada para recuperar extractos de texto relevantes. Este parámetro tiene un límite de 1.500 caracteres. Debe queryString ser una sola oración y debes evitar errores ortográficos en palabras clave con mucho contexto. Obligatorio.
dataSource Cadena Indica si se deben recuperar las extracciones de los conectores de SharePoint, OneDrive o Copilot. Los valores aceptables son sharePoint, oneDriveBusinessy externalItem. Obligatorio.
dataSourceConfiguration dataSourceConfiguration Contiene información de configuración adicional para los orígenes de datos aplicables. dataSourceConfiguration incluye un objeto llamado externalItem, donde puede configurar la recuperación de conectores de Copilot. Opcional.
filterExpression Cadena Expresión de lenguaje de consulta por palabra clave (KQL) con propiedades y atributos de conectores de SharePoint, OneDrive o Copilot consultables para definir el ámbito de la recuperación antes de que se ejecute la consulta. Puede usar ANDoperadores , OR, NOT, y desigualdad cuando corresponda al construir su filterExpression. Las propiedades de SharePoint y OneDrive admitidas para el filtrado son: Author, FileExtension, Filename, ModifiedByLastModifiedTimeInformationProtectionLabelIdPathFileTypeSiteIDy .Title Al filtrar el contenido de los conectores de Copilot, puede usar cualquier propiedad marcada como consultable en el esquema del conector de Copilot. Póngase en contacto con el administrador o desarrollador que configuró el conector de Copilot deseado para obtener una lista de propiedades marcadas como consultables. Microsoft no resolverá ningún problema con el filtrado de las propiedades de los conectores de SharePoint y Copilot que no se mencionan aquí. Puede utilizar varias propiedades y operadores al construir el filterExpressionarchivo . De forma predeterminada, no se aplica ningún ámbito. Asegúrese de que este parámetro tiene la sintaxis de KQL correcta antes de llamar a la API. De lo contrario, la consulta se ejecuta como si no hubiera ningún filterExpressionarchivo Opcional. Para conocer los procedimientos recomendados para las consultas filtradas, consulte Procedimientos recomendados.
resourceMetadata Colección string Una lista de campos de metadatos que se devolverán para cada elemento de la respuesta. Solo se pueden incluir en esta lista propiedades de metadatos recuperables. De forma predeterminada, no se devuelven metadatos. Opcional.
maximumNumberOfResults Int32 El número de resultados que se devuelven en la respuesta. Debe tener entre 1 y 25. De forma predeterminada, devuelve hasta 25 resultados. Opcional.
Parámetro Tipo Descripción
queryString Cadena Cadena de consulta en lenguaje natural usada para recuperar extractos de texto relevantes. Este parámetro tiene un límite de 1.500 caracteres. Debe queryString ser una sola oración y debes evitar errores ortográficos en palabras clave con mucho contexto. Obligatorio.
dataSource Cadena Indica si se deben recuperar las extracciones de los conectores de SharePoint, OneDrive o Copilot. Los valores aceptables son sharePoint, oneDriveBusinessy externalItem. Obligatorio.
dataSourceConfiguration dataSourceConfiguration Contiene información de configuración adicional para los orígenes de datos aplicables. dataSourceConfiguration incluye un objeto llamado externalItem, donde puede configurar la recuperación de conectores de Copilot. Opcional.
filterExpression Cadena Expresión de lenguaje de consulta por palabra clave (KQL) con propiedades y atributos de conectores de SharePoint, OneDrive o Copilot consultables para definir el ámbito de la recuperación antes de que se ejecute la consulta. Puede usar ANDoperadores , OR, NOT, y desigualdad cuando corresponda al construir su filterExpression. Las propiedades de SharePoint y OneDrive admitidas para el filtrado son: Author, FileExtension, Filename, ModifiedByLastModifiedTimeInformationProtectionLabelIdPathFileTypeSiteIDy .Title Al filtrar el contenido de los conectores de Copilot, puede usar cualquier propiedad marcada como consultable en el esquema del conector de Copilot. Póngase en contacto con el administrador o desarrollador que configuró el conector de Copilot deseado para obtener una lista de propiedades marcadas como consultables. Microsoft no resolverá ningún problema con el filtrado de las propiedades de los conectores de SharePoint y Copilot que no se mencionan aquí. Puede utilizar varias propiedades y operadores al construir el filterExpressionarchivo . De forma predeterminada, no se aplica ningún ámbito. Asegúrese de que este parámetro tiene la sintaxis de KQL correcta antes de llamar a la API. De lo contrario, la consulta se ejecuta como si no hubiera ningún filterExpressionarchivo Opcional. Para conocer los procedimientos recomendados para las consultas filtradas, consulte Procedimientos recomendados.
resourceMetadata Colección string Una lista de campos de metadatos que se devolverán para cada elemento de la respuesta. Solo se pueden incluir en esta lista propiedades de metadatos recuperables. De forma predeterminada, no se devuelven metadatos. Opcional.
maximumNumberOfResults Int32 El número de resultados que se devuelven en la respuesta. Debe tener entre 1 y 25. De forma predeterminada, devuelve hasta 25 resultados. Opcional.
includeThumbnails Booleano Indica si se deben incluir números de página y miniaturas en la respuesta de recuperación, si está disponible. Si varias extracciones hacen referencia a la misma página, solo se devuelve una única copia de la miniatura asociada con el resultado de recuperación. Opcional.

Respuesta

Si se realiza correctamente, esta acción devuelve un 200 OK código de respuesta y un retrievalResponse en el cuerpo de la respuesta.

Ejemplos

Ejemplo 1: Recuperar datos de SharePoint

En el ejemplo siguiente se muestra una solicitud para recuperar datos de SharePoint. La solicitud solicita que title se devuelvan los metadatos y author para cada elemento del que se recupera una extracción de texto. La respuesta incluye un máximo de 10 documentos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

▶ Pruébelo en la demostración interactiva

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
          "relevanceScore": 0.7588038775683956
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.6696818957446697
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "Corporate VPN",
        "author": "Jane Doe"
      },
        "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Ejemplo 2: Recuperación de datos de conectores de Copilot

En el ejemplo siguiente se muestra una solicitud para recuperar datos de conectores de Copilot. La solicitud solicita que title se devuelvan los metadatos y author para cada elemento del que se recupera una extracción de texto. La respuesta incluye un máximo de 10 documentos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

Ejemplo 3: Solicitudes por lotes a la API de recuperación

En el ejemplo siguiente se muestra cómo enviar solicitudes por lotes a la API de recuperación. La API de recuperación admite hasta 20 solicitudes por lote. La id carga de la solicitud debe ser una cadena que identifique de forma única cada solicitud del lote.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "sharePoint"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "externalItem"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "sharePoint"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "externalItem"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
                "relevanceScore": 0.8374363553387588
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.7465472642498679
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00"
            }
          },
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
                "relevanceScore": 0.7588038775683956
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.6696818957446697
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00"
            }
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
                "relevanceScore": 0.874
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.801
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          },
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
                "relevanceScore": 0.772
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.655
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          }
        ]
      }
    }
  ]
}

Ejemplo 4: Recuperar datos de un sitio de SharePoint específico

En el ejemplo siguiente se muestra una solicitud para recuperar datos de un sitio específico de SharePoint. El filterExpression parámetro especifica la ruta de acceso al sitio. La solicitud solicita que title se devuelvan los metadatos y author para cada elemento del que se recupera una extracción de texto. La respuesta incluye hasta cuatro documentos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Ejemplo 5: Recuperar datos de varios sitios de SharePoint

En el ejemplo siguiente se muestra una solicitud para recuperar datos de varios sitios de SharePoint. El filterExpression parámetro especifica las rutas de acceso a los sitios. La solicitud solicita que title se devuelvan los metadatos y author para cada elemento del que se recupera una extracción de texto. La respuesta debe incluir un máximo de cuatro documentos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Config",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Ejemplo 6: Recuperar datos de conectores de Copilot mediante identificadores de conexión específicos

En el ejemplo siguiente se muestra una solicitud que restringe la recuperación de conectores de Copilot a identificadores de conexión específicos. La solicitud solicita que title se devuelvan los metadatos y author para cada elemento del que se recupera una extracción de texto. La respuesta incluye hasta 10 documentos.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "dataSourceConfiguration": {
    "externalItem": {
      "connections": [
        {
          "connectionId": "ContosoITServiceNowKB"
        },
        {
          "connectionId": "ContosoHRServiceNowKB"
        }
      ]
    }
  },
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "dataSourceConfiguration": {
    "externalItem": {
      "connections": [
        {
          "connectionId": "ContosoITServiceNowKB"
        },
        {
          "connectionId": "ContosoHRServiceNowKB"
        }
      ]
    }
  },
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
          "relevanceScore": 0.772
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

Ejemplo 7: Uso de expresiones de filtro

En los ejemplos siguientes se muestran expresiones KQL que puede utilizar en la filterExpression propiedad en determinadas situaciones.

Filtrar en las propiedades del conector de Copilot

En este ejemplo, Label_Title es una propiedad consultable en el esquema del conector de Copilot de ServiceNow. La consulta filtra los elementos que contienen Corporate VPN en la Label_Title propiedad.

"filterExpression": "Label_Title:\"Corporate VPN\""

Filtrar los resultados de SharePoint en la Author propiedad

En este ejemplo, la consulta filtra los elementos con Megan Bowen como autora.

"filterExpression": "Author:\"Megan Bowen\""

Filtre los resultados de SharePoint en un intervalo de fechas específico mediante la LastModifiedTime propiedad

En este ejemplo, la consulta filtra los elementos modificados entre el 22 de julio de 2024 y el 8 de enero de 2025.

"filterExpression": "LastModifiedTime>= 2024-07-22 AND LastModifiedTime<= 2025-01-08"

Filtre los resultados de SharePoint mediante la FileExtension propiedad

En este ejemplo, la consulta filtra archivos con la extensión de archivo .docx, .pdf o .pptx.

"filterExpression": "FileExtension:\"docx\" OR FileExtension:\"pdf\" OR FileExtension:\"pptx\""

Filtre los resultados de SharePoint mediante la Filename propiedad

En este ejemplo, la consulta filtra los archivos denominados Contoso Mission Statement.docx.

"filterExpression": "Filename:\"Contoso Mission Statement.docx\""

Filtre los resultados de SharePoint mediante la FileType propiedad

En este ejemplo, la consulta filtra archivos PDF, presentaciones de PowerPoint y documentos de Word.

"filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\""

Determinar la confidencialidad de los resultados de SharePoint mediante el filtrado mediante la InformationProtectionLabelId propiedad

En este ejemplo, la consulta filtra los elementos con una etiqueta de protección de información específica.

"filterExpression": "InformationProtectionLabelId:\"f0ddcc93-d3c0-4993-b5cc-76b0a283e252\""

Filtre los resultados de SharePoint mediante la ModifiedBy propiedad

En este ejemplo, la consulta filtra los elementos modificados por Adele Vance.

"filterExpression": "ModifiedBy:\"Adele Vance\""

Filtre los resultados de SharePoint mediante la SiteID propiedad

En este ejemplo, la consulta filtra elementos de un sitio de SharePoint específico.

"filterExpression": "SiteID:\"e2cf7e40-d689-41de-99ee-a423811a253c\""

Filtre los resultados de SharePoint mediante la Title propiedad

En este ejemplo, la consulta filtra los elementos en Windows 10 Device el título.

"filterExpression": "Title:\"Windows 10 Device\""

Ejemplo 8: Incluir miniaturas de extractos

En el ejemplo siguiente se muestra una solicitud que agrega la includeThumbnails propiedad y la respuesta asociada que incluye miniaturas y los números de página asociados.

Solicitud

POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 2,
  "includeThumbnails": true
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588,
          "pageNumbers": [
            1
          ]
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679,
          "pageNumbers": [
            2
          ]
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      },
      "thumbnails": [
        {
          "pageNumber": 1,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
        {
          "pageNumber": 2,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
      ]
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679,
          "pageNumbers": [
            1,2
          ]
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Config",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Contenido relacionado

  • Last updated on