Récupérer les données d’ancrage

Importante

Les API sous la /beta version sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge.

L’API de récupération de Microsoft 365 Copilot récupère des extraits de texte pertinents à partir du contenu des connecteurs SharePoint, OneDrive et Copilot. La sécurité de l’API découpe le contenu pour l’utilisateur appelant et respecte les contrôles d’accès définis au sein du client. Utilisez l’API de récupération pour ancrer vos solutions d’IA générative sur les données Microsoft 365 tout en optimisant le rappel de contexte.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet
✅ ❌ ❌ ❌

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
Déléguée (compte professionnel ou scolaire) Files. Read.All, Sites.Read.All* ExternalItem.Read.All
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Non prise en charge. Non prise en charge.

* Pour récupérer du contenu SharePoint et OneDrive, vous avez besoin des deux Files. les autorisations Read.All et Sites.Read.All.

Requête HTTP

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

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

En-têtes de demande

Nom Description
Authorization Bearer {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.
Content-Type application/json. Obligatoire.

Corps de la demande

Dans le corps de la demande, fournissez une représentation JSON des paramètres.

Le tableau suivant répertorie les paramètres facultatifs et obligatoires que vous pouvez utiliser lorsque vous appelez cette action.

Paramètre Type Description
queryString String Chaîne de requête en langage naturel utilisée pour récupérer des extraits de texte pertinents. Ce paramètre a une limite de 1 500 caractères. Votre queryString doit être une seule phrase et vous devez éviter les fautes d’orthographe dans les mots clés riches en contexte. Obligatoire.
dataSource String Indique si les extraits doivent être récupérés à partir de connecteurs SharePoint, OneDrive ou Copilot. Les valeurs acceptables sont sharePoint, oneDriveBusiness, et externalItem. Obligatoire.
dataSourceConfiguration dataSourceConfiguration Contient des informations de configuration supplémentaires pour les sources de données applicables. dataSourceConfiguration comprend un objet appelé externalItem, dans lequel vous pouvez configurer la récupération des connecteurs Copilot. Facultatif.
filterExpression String Langage de requête par mots-clés expression (KQL) avec des propriétés et attributs de connecteurs SharePoint, OneDrive ou Copilot pouvant être interrogés pour étendre la récupération avant l’exécution de la requête. Vous pouvez utiliser AND, OR, NOTet les opérateurs d’inégalité le cas échéant lors de la construction de votre filterExpression. Les propriétés SharePoint et OneDrive prises en charge pour le filtrage sont les suivantes : Author, , FileExtensionFilename, SiteIDInformationProtectionLabelIdLastModifiedTimeModifiedByFileTypePathet .Title Lors du filtrage sur le contenu des connecteurs Copilot, vous pouvez utiliser n’importe quelle propriété marquée comme pouvant faire l’objet d’une requête dans le schéma du connecteur Copilot. Contactez l’administrateur ou le développeur qui a configuré le connecteur Copilot souhaité pour obtenir la liste des propriétés marquées comme pouvant faire l’objet d’une requête. Microsoft ne résoudra aucun problème lié au filtrage des propriétés de connecteurs SharePoint et Copilot non mentionnées ici. Vous pouvez utiliser plusieurs propriétés et opérateurs lors de la construction de votre filterExpressionfichier . Par défaut, aucune étendue n’est appliquée. Vérifiez que la syntaxe KQL de ce paramètre est correcte avant d’appeler l’API. Sinon, la requête s’exécute comme s’il n’y avait pas filterExpressionde . Facultatif. Pour connaître les meilleures pratiques relatives aux requêtes filtrées, reportez-vous à la rubrique Meilleures pratiques.
resourceMetadata String collection Liste des champs de métadonnées à renvoyer pour chaque élément de la réponse. Seules les propriétés de métadonnées récupérables peuvent être incluses dans cette liste. Par défaut, aucune métadonnée n’est renvoyée. Facultatif.
maximumNumberOfResults Int32 Nombre de résultats renvoyés dans la réponse. Doit être compris entre 1 et 25. Par défaut, renvoie jusqu’à 25 résultats. Facultatif.
Paramètre Type Description
queryString String Chaîne de requête en langage naturel utilisée pour récupérer des extraits de texte pertinents. Ce paramètre a une limite de 1 500 caractères. Votre queryString doit être une seule phrase et vous devez éviter les fautes d’orthographe dans les mots clés riches en contexte. Obligatoire.
dataSource String Indique si les extraits doivent être récupérés à partir de connecteurs SharePoint, OneDrive ou Copilot. Les valeurs acceptables sont sharePoint, oneDriveBusiness, et externalItem. Obligatoire.
dataSourceConfiguration dataSourceConfiguration Contient des informations de configuration supplémentaires pour les sources de données applicables. dataSourceConfiguration comprend un objet appelé externalItem, dans lequel vous pouvez configurer la récupération des connecteurs Copilot. Facultatif.
filterExpression String Langage de requête par mots-clés expression (KQL) avec des propriétés et attributs de connecteurs SharePoint, OneDrive ou Copilot pouvant être interrogés pour étendre la récupération avant l’exécution de la requête. Vous pouvez utiliser AND, OR, NOTet les opérateurs d’inégalité le cas échéant lors de la construction de votre filterExpression. Les propriétés SharePoint et OneDrive prises en charge pour le filtrage sont les suivantes : Author, , FileExtensionFilename, SiteIDInformationProtectionLabelIdLastModifiedTimeModifiedByFileTypePathet .Title Lors du filtrage sur le contenu des connecteurs Copilot, vous pouvez utiliser n’importe quelle propriété marquée comme pouvant faire l’objet d’une requête dans le schéma du connecteur Copilot. Contactez l’administrateur ou le développeur qui a configuré le connecteur Copilot souhaité pour obtenir la liste des propriétés marquées comme pouvant faire l’objet d’une requête. Microsoft ne résoudra aucun problème lié au filtrage des propriétés de connecteurs SharePoint et Copilot non mentionnées ici. Vous pouvez utiliser plusieurs propriétés et opérateurs lors de la construction de votre filterExpressionfichier . Par défaut, aucune étendue n’est appliquée. Vérifiez que la syntaxe KQL de ce paramètre est correcte avant d’appeler l’API. Sinon, la requête s’exécute comme s’il n’y avait pas filterExpressionde . Facultatif. Pour connaître les meilleures pratiques relatives aux requêtes filtrées, reportez-vous à la rubrique Meilleures pratiques.
resourceMetadata String collection Liste des champs de métadonnées à renvoyer pour chaque élément de la réponse. Seules les propriétés de métadonnées récupérables peuvent être incluses dans cette liste. Par défaut, aucune métadonnée n’est renvoyée. Facultatif.
maximumNumberOfResults Int32 Nombre de résultats renvoyés dans la réponse. Doit être compris entre 1 et 25. Par défaut, renvoie jusqu’à 25 résultats. Facultatif.
includeThumbnails Booléen Indique s’il faut inclure les numéros de page et les miniatures dans la réponse de récupération, le cas échéant. Si plusieurs extraits font référence à la même page, une seule copie de la miniature associée est renvoyée avec l’accès à la récupération. Facultatif.

Réponse

En cas de succès, cette action retourne un 200 OK code de réponse et une retrievalResponse dans le corps de la réponse.

Exemples

Exemple 1 : récupérer des données à partir de SharePoint

L’exemple suivant illustre une demande de récupération de données à partir de SharePoint. La demande demande que les title métadonnées et author soient renvoyées pour chaque élément à partir duquel un extrait de texte est récupéré. La réponse comprend un maximum de 10 documents.

Demande

L’exemple suivant illustre la demande.

▶ Essayez-le dans la démo interactive

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 2 : Récupérer des données à partir de connecteurs Copilot

L’exemple suivant montre une demande de récupération de données à partir de connecteurs Copilot. La demande demande que les title métadonnées et author soient renvoyées pour chaque élément à partir duquel un extrait de texte est récupéré. La réponse comprend un maximum de 10 documents.

Demande

L’exemple suivant illustre la demande.

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 3 : demandes par lots à l’API de récupération

L’exemple suivant montre comment traiter des demandes par lots à l’API de récupération. L’API de récupération prend en charge jusqu’à 20 requêtes par lot. La id charge utile de la requête doit être une chaîne identifiant de manière unique chaque demande dans le lot.

Demande

L’exemple suivant illustre la demande.

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

Réponse

L’exemple suivant illustre la réponse.

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": {}
          }
        ]
      }
    }
  ]
}

Exemple 4 : Récupérer des données à partir d’un site SharePoint spécifique

L’exemple suivant illustre une demande de récupération de données à partir d’un site SharePoint spécifique. Le filterExpression paramètre spécifie le chemin d’accès au site. La demande demande que les title métadonnées et author soient renvoyées pour chaque élément à partir duquel un extrait de texte est récupéré. La réponse comprend jusqu’à quatre documents.

Demande

L’exemple suivant illustre la demande.

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 5 : Récupérer des données à partir de plusieurs sites SharePoint

L’exemple suivant illustre une demande de récupération de données à partir de plusieurs sites SharePoint. Le filterExpression paramètre spécifie les chemins d’accès aux sites. La demande demande que les title métadonnées et author soient renvoyées pour chaque élément à partir duquel un extrait de texte est récupéré. La réponse doit comprendre un maximum de quatre documents.

Demande

L’exemple suivant illustre la demande.

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 6 : Récupérer des données à partir de connecteurs Copilot à l’aide d’ID de connexion spécifiques

L’exemple suivant montre une demande qui limite la récupération des connecteurs Copilot à des ID de connexion spécifiques. La demande demande que les title métadonnées et author soient renvoyées pour chaque élément à partir duquel un extrait de texte est récupéré. La réponse comprend jusqu’à 10 documents.

Demande

L’exemple suivant illustre la demande.

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Exemple 7 : utiliser des expressions de filtre

Les exemples suivants montrent des expressions KQL que vous pouvez utiliser dans la filterExpression propriété pour des scénarios spécifiques.

Filtrer sur les propriétés du connecteur Copilot

Dans cet exemple, Label_Title se trouve une propriété pouvant faire l’objet d’une requête dans le schéma de connecteur Copilot de ServiceNow. La requête filtre les éléments qui contiennent Corporate VPN dans la Label_Title propriété.

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

Filtrer les résultats SharePoint sur la Author propriété

Dans cet exemple, la requête porte sur des éléments ayant Megan Bowen comme auteur.

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

Filtrer les résultats SharePoint sur une plage de dates spécifique à l’aide de la LastModifiedTime propriété

Dans cet exemple, la requête filtre sur les éléments modifiés entre le 22 juillet 2024 et le 8 janvier 2025.

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

Filtrer les résultats SharePoint à l’aide de la FileExtension propriété

Dans cet exemple, la requête filtre les fichiers portant l’extension de fichier .docx, .pdf ou .pptx.

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

Filtrer les résultats SharePoint à l’aide de la Filename propriété

Dans cet exemple, la requête filtre sur les fichiers nommés Contoso Mission Statement.docx.

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

Filtrer les résultats SharePoint à l’aide de la FileType propriété

Dans cet exemple, la requête filtre les fichiers PDF, les présentations PowerPoint et les documents Word.

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

Déterminer la sensibilité des résultats SharePoint en filtrant à l’aide de la InformationProtectionLabelId propriété

Dans cet exemple, la requête porte sur les éléments associés à une étiquette de protection des informations spécifique.

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

Filtrer les résultats SharePoint à l’aide de la ModifiedBy propriété

Dans cet exemple, la requête porte sur les éléments modifiés par Adele Vance.

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

Filtrer les résultats SharePoint à l’aide de la SiteID propriété

Dans cet exemple, la requête porte sur des éléments provenant d’un site SharePoint spécifique.

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

Filtrer les résultats SharePoint à l’aide de la Title propriété

Dans cet exemple, la requête porte sur les éléments dont Windows 10 Device le titre porte dessus.

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

Exemple 8 : inclure des miniatures pour les extraits

L’exemple suivant montre une requête qui ajoute la includeThumbnails propriété et la réponse associée, qui inclut les miniatures et les numéros de page associés.

Demande

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
}

Réponse

L’exemple suivant illustre la réponse.

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

Contenu connexe

  • Last updated on