Kurz – použití rozhraní API Microsoft Purview k použití vašich zásad ve svých aplikacích

Všechny aplikace, včetně podnikových aplikací AI, zpracovávají citlivá data, která vyžadují ochranu před únikem dat, neoprávněným přístupem a porušením dodržování předpisů. zásady Microsoft Purview pomáhají organizacím chránit citlivé informace. Vaše aplikace se můžou integrovat s rozhraními API Microsoft Purview, aby se zajistilo, že zásady Microsoft Purview podporují stav zabezpečení vaší aplikace.

Tento článek obsahuje návod, jak přidat rozhraní API Microsoft Purview do stávající podnikové aplikace, abyste mohli využívat zásady. Příklad použitý v tomto článku je aplikace GenAI, ale stejné koncepty se dají snadno použít i pro aplikace bez AI. Na konci tohoto názorného postupu porozumíte:

Kdy a jak volat rozhraní API Purview pro známého uživatele pro aktivitu, kterou ve vaší aplikaci provádí.
Vyhodnoťte vstupy uživatelů a výstupy aplikace (například výzvy a odpovědi na AI nebo jakýkoli text odeslaný uživatelem a vygenerovaný obsah) proti těmto zásadám.
Vynucujte v aplikaci akce zásad, například blokování nebo udržování souladu se změnami zásad ve vašem tenantovi.

Note

Pomocí rozhraní API Microsoft Purview můžete odesílat data do Microsoft Purview a podporovat zásady Purview přidružené k datům. K dispozici nejsou žádná rozhraní API pro extrakci dat nebo analýzy z Microsoft Purview.

Předpoklady

Než začnete, ujistěte se, že máte:

Předplatné Azure s nakonfigurovaným Microsoft Purview.
Aplikace zaregistrovaná v Microsoft Entra ID s příslušnými oprávněními.
Základní znalost volání Microsoft Graph API
Přístup k uživatelským vstupům a výstupům aplikace, které chcete vyhodnotit (například výzvy a odpovědi v aplikaci GenAI nebo text nahraný nebo stažený obchodní aplikací).
Pro kompletní testování vytvořte zásady ve vašem Portál Microsoft Purview. Další informace o dostupných zásadách najdete v článku Použití Microsoft Purview ke správě zabezpečení dat a dodržování předpisů pro aplikace AI registrované v Entra.

Important

Pokud chcete vytvořit zásadu ochrany před únikem informací, která se vztahuje na vaši aplikaci zaregistrovanou v Entra, musíte použít rutinu PowerShellu New-DlpComplianceRule . Portál Microsoft Purview v současné době nepodporuje vytváření zásad ochrany před únikem informací pro aplikace zaregistrované v Entra. Další informace naleznete v tématu New-DlpComplianceRule.

Jak začít s Microsoft Graph

Pokud s používáním Microsoft Graph úplně začínáte, přečtěte si téma Microsoft Graph Základy.

Následující kroky vám pomůžou experimentovat s rozhraním API. Tento postup nepoužívejte k plánování produkčního nasazení aplikace.

Přečtěte si informace o rozhraních API Microsoft Purview v Microsoft Graph pro integraci do vaší aplikace. Tato rozhraní API jsou podrobně popsána dále v tomto článku.
Požádejte správce Entra , aby vaši aplikaci zaregistroval v Entra. V závislosti na zásadách vaší společnosti vám může být umožněno zaregistrovat aplikaci, nebo možná budete muset projít registračním procesem. Nezapomeňte se s vaším správcem Entra seznámit s procesem, který se má provést pro vašeho tenanta. Další informace naleznete v následujících zdrojích:
Nakonfigurujte aplikaci s požadovanými oprávněními. Ujistěte se, že vaše aplikace požádá o tato oprávnění, když požádá o token z Microsoft Graph. K aplikaci můžete například přiřadit Content.Process.User oprávnění a ProtectionScopes.Compute.User oprávnění. Další informace najdete v tématu Microsoft Graph reference k oprávněním a autorizace aplikací, prostředků a úloh pomocí Microsoft Entra ID.
Požádejte správce tenanta, aby nakonfigurovali Microsoft Purview zásady a nastavení. Další informace najdete v tématu Konfigurace řešení Microsoft Purview ve správě stavu zabezpečení dat (DSPM) pro AI pro vlastní aplikace AI. Správce musí k vytvoření zásad ochrany před únikem informací pro vaše aplikace zaregistrované v Entra použít rutinu New-DlpComplianceRule PowerShellu. Tento scénář Portál Microsoft Purview nepodporuje.
Aplikaci otestujte. Další informace naleznete v tématu Jak otestovat aplikaci AI pomocí rozhraní Purview API.

Přehled integrace rozhraní API Microsoft Purview

Vaše aplikace provádí dvě klíčová volání rozhraní API pro podporu zásad Microsoft Purview:

Compute protection scopes: Určuje, které aktivity uživatele (uploadText, downloadText, uploadFile, downloadFile) vyžadují vyhodnocení zásad pro konkrétního uživatele.
Process content: Vaše aplikace odesílá aktivitu související s obsahem k vyhodnocení zásad a vrátí akce zásad, které musí vaše aplikace vynutit (například blokování nebo zjišťování změn zásad).

Následující části obsahují podrobné pokyny k implementaci, včetně příkladů kódu a způsobu zpracování odpovědí.

Podrobný návod k ukázkové aplikaci, která tato volání rozhraní API provádí, najdete ve videu Microsoft Reactor.

Krok 1: Rozsahy ochrany výpočetních prostředků pro uživatele

Prvním krokem je určit, které zásady a omezení se vztahují na konkrétního uživatele na základě aktivit, které můžou ve vaší aplikaci provádět (například nahrání textového zadání nebo výzvy nebo stažení odpovědí AI). Tomu se říká výpočet rozsahu ochrany uživatele.

Rozsahy ochrany jsou abstrakcí zásad tenanta, které se vztahují na uživatele. U všech uživatelů a aktivit, které uživatel provádí ve vaší aplikaci, chcete vypočítat rozsah ochrany. Rozsah ochrany označuje akci, kterou má aplikace provést dále, což může být vyhodnoceno a blokováno, vyhodnocovat a neblokovat nebo není potřeba žádné vyhodnocení.

Note

Doporučujeme, aby vaše aplikace hned po ověření uživatele zavolala Vypočítat rozsahy ochrany. Pokud chcete volatprotectionScopes/compute, musíte mít Entra ID uživatele.

Pokud máte pouze userPrincipalName uživatele, použijte následující adresu URL k získání ID objektu.

GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}?$select=id

Tady je příklad požadavku na protectionScopes/compute.

POST https://graph.microsoft.com/v1.0/users/7c1f8f10-cba8-4a8d-9449-db4b876d1ef70/dataSecurityAndGovernance/protectionScopes/compute
Content-type: application/json

{
   "activities": "uploadText,downloadText",
   "locations": [
      {
         "@odata.type": "microsoft.graph.policyLocationApplication",
         "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
      }
   ]
}

V předchozím volání pro výpočet rozsahu ochrany musíte zahrnout aktivity uživatele, které uživatel provádí ve vaší aplikaci. Mezi akceptované aktivity uživatelů patří:

uploadText – uživatelé do aplikace odesílají textové zadání (například výzva odeslaná do AI, zpráva v chatovací aplikaci nebo text vložený do formuláře).
downloadText – textový výstup, který aplikace vrátí uživateli (například odpověď AI nebo vygenerovaný text dokumentu).
uploadFile – uživatel odešle do aplikace soubor (například soubor připojený k výzvě ke zpracování).
downloadFile – soubor vrácený aplikací uživateli (například soubor vygenerovaný AI nebo exportovaný obchodní aplikací).

Další informace o aktivitách uživatelů naleznete v části hodnoty userActivityTypes.

Volání pro výpočet oborů ochrany vrátí kolekci policyUserScopes. Zde je příklad odpovědi se 2 rozsahy ochrany.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.policyUserScope)",
  "value": [
    {
      "activities": "uploadText,downloadText",
      "executionMode": "evaluateOffline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    },
    {
      "activities": "uploadText",
      "executionMode": "evaluateInline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    }
  ]
}

Je důležité, aby vaše aplikace tuto odpověď zpracovala a určila, která aktivita uživatele (například uploadText) vyžaduje vyhodnocení zásad u obsahu odeslaného uživatelem nebo zaslaného uživateli.

Pokud je vrácená kolekce policyUserScopes prázdná: Pro aktivitu uživatele se nevztahují žádné zásady. Pokud se pro tohoto uživatele pro tuto aktivitu nevztahují žádné zásady, doporučujeme volat aktivitu obsahu pro protokolování aktivit pro dodržování předpisů auditu a detekci anomálií. Toto nastavení můžete nastavit jako konfigurovatelné v aplikaci.

Pokud kolekce policyUserScopes obsahuje obory: Když se vrátí obory ochrany, musí aplikace analyzovat odpověď kontrolou hodnot activities jednotlivých oborů ochrany a executionMode pro každý obor ochrany. V předchozím příkladu se v kolekci policyUserScopes vracejí 2 oblasti ochrany.

executionMode pomáhá určit, jaké omezení se vztahuje na konkrétního uživatele pro aktivitu uživatele. Následující seznam obsahuje platné hodnoty pro executionMode:

evaluateOffline: Znamená, že můžete provést asynchronní volání pro vyhodnocení obsahu proti zásadám při volání processContent.
evaluateInline: Znamená to, že hlavní vlákno vaší aplikace musí být blokováno, dokud se volání z processContent nevrátí.

Další informace naleznete v části hodnoty executionMode.

Tip

Pokud protectionScopes/compute vždy vrací oblasti ochrany, u nichž je hodnota executionMode vždy rovna evaluateOffline, ověřte, že jste zásadu ochrany před únikem informací vytvořili pomocí rutiny PowerShellu New-DlpComplianceRule. Ověřte, že jsou zásady uvedené a povolené v zásadách kolekce DSPM>. Zásady vytvořené prostřednictvím uživatelského rozhraní Portál Microsoft Purview se nevztahují na aplikace zaregistrované v Entra.

Označuje activity aktivitu uživatele, na kterou se vztahuje obor ochrany. Můžete zjistit, že se activity opakuje ve více než 1 oboru ochrany. Všimněte si například v předchozí ukázce, že se uploadText vrací v obou oborech ochrany. V takovém případě musí vaše aplikace na tuto aktivitu uživatele použít přísnější obor ochrany.

Následující příklad ukazuje, jak by aplikace parsovala předchozí vrácenou policyUserScopes kolekci:

Analýzou prvního rozsahu ochrany vidíme následující informace:
- uploadText (nebo výzvy odeslané do AI) a downloadText (nebo odpovědi z AI) musí být vyhodnoceny offline.
Při analýze druhého rozsahu ochrany vidíme následující informace:
- uploadText (nebo prompty zaslané AI) musí být vyhodnoceny přímo v textu.
U jakékoli jiné aktivity uživatele (uploadFile, downloadFile) se na tyto aktivity uživatele nevztahují žádné obory ochrany. Zvažte vyvolání aktivity Content, jak bylo popsáno dříve.

Logika, která musí vaše aplikace implementovat pro tyto různé aktivity uživatelů, jsou následující:

Aktivita uživatele	Akce v aplikaci
`uploadText`	Blokovat hlavní vlákno při volání `processContent`.
`downloadText`	Při volání `processContent`proveďte asynchronní volání .

Important

Uložte do mezipaměti hodnotu ETag: Volání protectionScopes/compute vrací hlavičku ETag, která představuje aktuální stav rozsahů ochrany pro tohoto uživatele. Aplikace musí tuto hodnotu uložit do mezipaměti a odeslat ji se všemi voláními processContent.

Krok 2: Zpracování obsahu

Dále může být na základě stavu rozsahu ochrany uživatele potřeba, aby vaše aplikace zavolala processContent.

Jak bylo popsáno výše, veškeré aktivity uživatele, u nichž executionMode bylo buď evaluateInline, nebo evaluateOffline, musí volat processContent.

Při volání odešlete hodnotu ETag, kterou si vaše aplikace uložila do mezipaměti z volání protectionScopes/compute v kroku 1, aby bylo možné určit, zda byly ve vašem tenantovi provedeny změny zásad. Hodnotu ETag odešlete v hlavičce If-None-Match.

Tady je příklad volání processContent.

POST https://graph.microsoft.com/v1.0/me/dataSecurityAndGovernance/processContent
Content-Type: application/json

{
    "contentToProcess": {
       "contentEntries": [
          {
             "@odata.type": "microsoft.graph.processConversationMetadata",
             "identifier": "07785517-9081-4fe7-a9dc-85bcdf5e9075",
             "content": {
                "@odata.type": "microsoft.graph.textContent", 
                "data": "Write an acceptance letter for Alex Wilber with Credit card number 4532667785213500, ssn: 120-98-1437 at One Microsoft Way, Redmond, WA 98052"
             },
             "name":"PC Purview API Explorer message",
             "correlationId": "d63eafd2-e3a9-4c1a-b726-a2e9b9d9580d",
             "sequenceNumber": 0, 
             "isTruncated": false,
             "createdDateTime": "2025-05-27T17:23:20",
             "modifiedDateTime": "2025-05-27T17:23:20"
          }
       ],
       "activityMetadata": { 
          "activity": "uploadText"
       },
       "deviceMetadata": {
          "deviceType": "Unmanaged",
          "operatingSystemSpecifications": {
             "operatingSystemPlatform": "Windows 11",
             "operatingSystemVersion": "10.0.26100.0" 
          },
          "ipAddress": "127.0.0.1"
       },
       "protectedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2",
          "applicationLocation":{
             "@odata.type": "microsoft.graph.policyLocationApplication",
             "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
          }
       },
       "integratedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2" 
       }
    }
}

Note

Pokyny k implementaci konverzací nebo vláken:

Pokud vaše aplikace podporuje více vláken nebo konverzací (například vlákna chatu v aplikaci AI nebo v aplikaci pro zasílání zpráv), použijte pro každé vlákno jedinečné correlationId vlákno.
Pokud udržujete kontext konverzace v daném vlákně, zvýší se sequenceNumber pro každou zprávu uživatele (například 0, 1, 2 atd.).

Tady je příklad odpovědi od processContent.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.processContentResponse",
  "protectionScopeState": "modified",
  "policyActions": [
    {
      "@odata.type": "#microsoft.graph.restrictAccessAction",
      "action": "restrictAccess",
      "restrictionAction": "block"
    }
  ],
  "processingErrors": []
}

V předchozím příkladu existují dvě akce, které vaše aplikace musí provést:

processContentResponse obsahuje vlastnost protectionScopeState, která je nastavena na modified. modified označuje, že se změnily zásady v tenantovi. Vzhledem k tomu, že se zásady změnily, musí vaše aplikace nejprve zavolat protectionScopes/compute , aby získala nové obory ochrany pro daného uživatele, které jsou popsány v kroku 1. Ujistěte se, že novou ETag hodnotu ukládáte do mezipaměti.
policyActions Vzhledem k tomu, že kolekce není prázdná, musí vaše aplikace procházet jednotlivé action kroky, aby určila příslušnou akci, která musí provést. V tomto příkladu znamená, restrictAccess že aplikace musí uživateli zablokovat požadovanou akci. Kdyby byla kolekce policyActions v processContentResponse prázdná, vaše aplikace by pokračovala v požadované aktivitě. Pokud vytváříte agenty, agent musí také blokovat před voláním jiného agenta, když je action nastaveno na restrictAccess.

Important

Pokud od vašeho posledního volání processContent uplynulo 60 minut, doporučujeme zavolat Compute protection scopes, abyste zjistili, zda se na uživatele nyní vztahují nějaké změny zásad provedené v tenantu. Pokud došlo ke změně, která se nyní vztahuje na uživatele, volání vrátí protectionScopes/compute novou ETag hodnotu, která musí být uložena v mezipaměti ve vaší aplikaci a použita při volání processContent.

Last updated on 2026-07-02

Kurz – použití rozhraní API Microsoft Purview k použití vašich zásad ve svých aplikacích

Předpoklady

Jak začít s Microsoft Graph

Přehled integrace rozhraní API Microsoft Purview

Krok 1: Rozsahy ochrany výpočetních prostředků pro uživatele

Krok 2: Zpracování obsahu

Další materiály