Quickstart: List Protection Templates (C++)

2025-04-12

This Quickstart shows you how to use the MIP Protection SDK, to protection templates available to the user.

Önkoşullar

Henüz yapmadıysanız devam etmeden önce aşağıdaki önkoşulları tamamladığınızdan emin olun:

Complete Quickstart - Client application initialization - Protection SDK (C++) first, which builds a starter Visual Studio solution. This "List protection templates" Quickstart relies on the previous one, for proper creation of the starter solution.
Optionally: Review RMS Templates concepts.

Add logic to list the protection templates

Add logic to list protection templates available to a user, using the Protection engine object.

Open the Visual Studio solution you created in the previous "Quickstart - Client application initialization - Protection SDK (C++)" article.
Çözüm Gezgini'ni kullanarak, projenizde yönteminin uygulanmasını main() içeren .cpp dosyasını açın. It defaults to the same name as the project containing it, which you specified during project creation.
using etiketinden sonra using mip::ProtectionEngine; yönergesini dosyanın en üstüne yakın bir yere ekleyin.
```
using std::endl;
```

Toward the end of the main() body, below the closing brace } of the last catch block and above return 0; (where you left off in the previous Quickstart), insert the following code:

 // List protection templates
 const shared_ptr<ProtectionEngineObserver> engineObserver = std::make_shared<ProtectionEngineObserver>();
 // Create a context to pass to 'ProtectionEngine::GetTemplateListAsync'. That context will be forwarded to the
 // corresponding ProtectionEngine::Observer methods. In this case, we use promises/futures as a simple way to detect
 // the async operation completes synchronously.
 auto loadPromise = std::make_shared<std::promise<vector<shared_ptr<mip::TemplateDescriptor>>>>();
 std::future<vector<shared_ptr<mip::TemplateDescriptor>>> loadFuture = loadPromise->get_future();
 engine->GetTemplatesAsync(engineObserver, loadPromise);
 auto templates = loadFuture.get();

 cout << "*** Template List: " << endl;

 for (const auto& protectionTemplate : templates) {
     cout << "Name: " << protectionTemplate->GetName() << " : " << protectionTemplate->GetId() << endl;
 }

Erişim belirteçleri oluşturmak için PowerShell betiği oluşturma

Uygulamanızda AuthDelegateImpl::AcquireOAuth2Token SDK tarafından istenen erişim belirteçleri oluşturmak için aşağıdaki PowerShell betiğini kullanın. The script uses the Get-ADALToken cmdlet from the ADAL.PS module you installed earlier, in "MIP SDK Setup and configuration".

Bir PowerShell Betik dosyası (.ps1 uzantısı) oluşturun ve aşağıdaki betiği kopyalayıp dosyaya yapıştırın:

$authority ve $resourceUrl daha sonra, aşağıdaki bölümde güncelleştirilecektir.
$appId ve $redirectUri değerlerini, Microsoft Entra uygulama kaydınızda belirttiğiniz değerlerle eşleşecek şekilde güncelleştirin.

$authority = '<authority-url>'                   # Specified when SDK calls AcquireOAuth2Token()
$resourceUrl = '<resource-url>'                  # Specified when SDK calls AcquireOAuth2Token()
$appId = '<app-ID>'                              # App ID of the Azure AD app registration
$redirectUri = '<redirect-uri>'                  # Redirect URI of the Azure AD app registration
$response = Get-ADALToken -Resource $resourceUrl -ClientId $appId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:RefreshSession
$response.AccessToken | clip                     # Copy the access token text to the clipboard

Betik dosyasını kaydederek istemci uygulamanız tarafından istendiğinde daha sonra çalıştırabilirsiniz.

Uygulamayı derleme ve test etme

Son olarak, istemci uygulamanızı derleyin ve test edin.

Use Ctrl+Shift+b (Build Solution) to build your client application. Derleme hatanız yoksa, uygulamanızı çalıştırmak için F5 (Hata ayıklamayı başlat) kullanın.
Projeniz başarıyla derlenip çalıştırılırsa, SDK yönteminizi AcquireOAuth2Token() her çağırdığında uygulama bir erişim belirteci ister. You can reuse a previously generated token, if prompted multiple times and the requested values are the same:
Komut istemi için bir erişim belirteci oluşturmak üzere PowerShell betiğinize geri dönün ve:
- $authority ve $resourceUrl değişkenlerini güncelleyin. Bunlar, 2. adımda konsol çıkışında belirtilen değerlerle eşleşmelidir.
- PowerShell betiğini çalıştırın. Cmdlet, Get-ADALToken aşağıdaki örneğe benzer şekilde bir Microsoft Entra kimlik doğrulama istemi tetikler. 2. adımda konsol çıkışında sağlanan hesabın aynısını belirtin. Oturum başarıyla açıldıktan sonra erişim belirteci panoya kopyalanacaktır.
- Uygulamanın oturum açma hesabı altında çalışırken MIP API'lerine erişmesine izin vermek için de onay vermeniz gerekebilir. Microsoft Entra uygulama kaydı önceden onaylanmamışsa ("MIP SDK kurulumu ve yapılandırmasında belirtildiği gibi") veya farklı bir kiracıdan (uygulamanızın kayıtlı olduğu hesap dışında) bir hesapla oturum açtığınızda bu durum ortaya çıkar. Onayınızı kaydetmek için Kabul Et'e tıklamanız yeterlidir.

After pasting the access token into the prompt from step #2, your console output should show the protection templates , similar to the following example:

*** Template List:
Name: Confidential \ All Employees : a74f5027-f3e3-4c55-abcd-74c2ee41b607
Name: Highly Confidential \ All Employees : bb7ed207-046a-4caf-9826-647cff56b990
Name: Confidential : 174bc02a-6e22-4cf2-9309-cb3d47142b05
Name: Contoso Employees Only : 667466bf-a01b-4b0a-8bbf-a79a3d96f720

C:\MIP Sample Apps\ProtectionQS\Debug\ProtectionQS.exe (process 8252) exited with code 0.
To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.

Press any key to continue . . .

Uyarı

Copy and save the ID of one or more of the protection templates (for example, f42a3342-8706-4288-bd31-ebb85995028z), as you will use it in the next Quickstart.

Sorun giderme

C++ uygulamasını yürütme sırasında karşılaşılan sorunlar

Özet	Hata mesajı	Çözüm
Hatalı erişim belirteci	Bir özel durum oluştu... Erişim belirteci yanlış mı/süresi dolmuş mu? Başarısız API çağrısı: profile_add_engine_async Başarısız: [class mip::PolicySyncException] politika edinme başarısız oldu, İstek, HTTP durum kodu 401 ile başarısız oldu, x-ms-diagnostics: [2000001; reason="İstekle gönderilen OAuth belirteci ayrıştırılamıyor."; error_category="invalid_token"], correlationId:[35bc0023-3727-4eff-8062-000006d5d672] C:\VSProjects\MipDev\Quickstarts\AppInitialization\x64\Debug\AppInitialization.exe (işlem 29924) 0 koduyla çıktı. Bu pencereyi kapatmak için herhangi bir tuşa basın. . .	Projeniz başarıyla derlenmişse ancak soldaki gibi bir çıkış görüyorsanız, `AcquireOAuth2Token()` yönteminizde büyük olasılıkla geçersiz veya süresi dolmuş bir belirteciniz vardır. Go back to Create a PowerShell script to generate access tokens and regenerate the access token, update `AcquireOAuth2Token()` again, and rebuild/retest. Ayrıca tek sayfalı jwt.ms web uygulamasını kullanarak belirteci ve taleplerini inceleyip doğrulayabilirsiniz.

Sonraki Adımlar

Now that you've learned how to list the protection templates available to an authenticated user, try the next quickstart:

[Encrypt and Decrypt text](quick-protection-encrypt-decrypt text-cpp.md)