Aide-mémoire des actions personnalisées

Cet article fournit une série de conseils pour vous aider à maximiser l’efficacité de votre script PowerShell lors de la création d’une action personnalisée dans CoreView :

• Get-DomainFromSid : elle extrait le domaine à partir d’une valeur SID.

Exemple :

Get-DomainFromSid -Sid S-1-5-21-1454471165-1004335555-1606986666-6666

• Get-ServerFromDn : elle extrait le domaine à partir d’un distinguished name.

Exemple :

Get-ServerFromDn -dn "CN=user_1,DC=child,DC=server,DC=local"

• Get-ListDomains : cette fonction fournit les domaines d’une forêt.

Exemple :

Get-ListDomains

• Get-ReverseOrganizationUnit : si la valeur commence par DC=, la fonction inverse le chemin.

Exemple :

Get-ReverseOrganizationUnit -ou "DC=local,DC=contoso,OU=folder"

• unicode : elle transforme une chaîne en UTF-8. 

Exemple :

unicode -str "value"

• Get-CountriesLookup : elle contient une table de correspondance des pays.

• Get-CountryCodeFromDisplayName : cette fonction renvoie le code ISO à partir du nom d’affichage d’un pays. 

Exemple :

Get-CountryCodeFromDisplayName -displayName "Italy"

• Get-CountryDisplayNameFromCode : cette fonction renvoie le nom d’affichage à partir du code ISO d’un pays. 

Exemple :

Get-CountryDisplayNameFromCode -countryCode "IT"

• Get-CvOnpremExchangeCredential : cette fonction récupère l’objet d’identification On-Premises Exchange. Cependant, cette fonction est limitée à un seul contexte de forêt.
• Get-CvADCredential : cette fonction récupère les informations d’identification à partir d’une session Active Directory (AD) ouverte. Elle est limitée à un seul contexte de forêt.
• Get-CvEmailAddresses : étant donné une chaîne en entrée contenant une ou plusieurs adresses e-mail séparées par une virgule, cette fonction renvoie une liste d’adresses e-mail même si certains éléments contiennent une virgule dans leur nom.

Exemple :

Get-CvEmailAddresses -emailAddresses "fake@domain.com,x500:/o=ExchangeLabs/ou=Exchange Administrative Group (test)/cn=Recipients/cn=1511b2015ac3521f8355f08ca5be1af0-my, test"

• Get-CvGroupCategoryFromValue : étant donné une valeur de type de groupe (un entier) et un e-mail, cette fonction renvoie le type, afin que nous puissions comprendre si ce groupe est un groupe de sécurité ou de distribution.

Exemple :

Get-CvGroupCategoryFromValue -groupTypeValue 8 -mail "fake_distribution@domain.com"

• Replace-Upn : cette fonction remplace un caractère simple ' par un double ''.

Exemple :

Replace-Upn -upn "user'c.example@contoso.com"

• Refresh-CVGraphToken : cette fonction est conçue pour actualiser le jeton pour la session Microsoft Graph. Elle est particulièrement utile lorsque vous devez vous assurer que le jeton de votre session est valide et à jour.
   
• Get-InfrastructureMasterByDomain : cette fonction obtient la valeur d’un rôle au niveau du domaine appelé Infrastructure Master.

Exemple :

Get-InfrastructureMasterByDomain -domain "contoso.local"

• ConvertFrom-CVCanonicalObject : cette fonction convertit un Canonical Name (CN) en Distinguished Name (DN).

Exemple :

ConvertFrom-CVCanonicalObject -CanonicalName "Constoso.local/OU Users/myUser"

• Retry-CvCommand : cette fonction est conçue pour réessayer un bloc de script plusieurs fois. Cela est utile lorsqu’une opération peut échouer de manière intermittente ou que les données ne sont pas immédiatement disponibles. 

La fonction accepte six paramètres :

1. $scriptBlock : il s’agit de la commande que vous voulez exécuter. Elle doit être passée sous forme de script block.
2. $params : ce sont les paramètres de la commande dans le script block.
3. $retryCount : il s’agit d’un paramètre optionnel qui spécifie le nombre de fois que la commande doit être réessayée si elle échoue. La valeur par défaut est 10.
4. $sleepTime : il s’agit d’un paramètre optionnel qui spécifie la durée (en secondes) pendant laquelle la fonction doit attendre avant de réessayer la commande. La valeur par défaut est de 3 secondes.
5. $throwException : il s’agit d’un paramètre optionnel qui spécifie si une exception doit être levée si la commande échoue après toutes les tentatives.
6. $stopOnNull : lorsqu’il est défini sur $true, la fonction arrête le modèle de nouvelle tentative si le résultat du script block est null, même si le nombre maximal de tentatives n’a pas été atteint.

Exemples :

# Cas d’usage 1 : nouvelle tentative avec exception levée
# Description : la fonction Retry-CvCommand tente d’exécuter le script block fourni 'get-aduser' trois fois pour l’identité 'fake@contoso.com' donnée. La fonction est configurée pour lever une exception (ErrorAction Stop) si l’utilisateur n’existe pas. Dans ce scénario, après trois tentatives, la fonction lève une exception indiquant que l’utilisateur n’existe pas.
    $sbUseCase1 ={
        param ($identity)
        get-aduser -Identity $identity -ErrorAction Stop
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase1 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $true
# Cas d’usage 2 : nouvelle tentative sans gestion des exceptions
# Description : la fonction Retry-CvCommand réessaie d’exécuter le script block 'get-aduser' trois fois pour l’identité 'fake@contoso.com' donnée. Cependant, cette fois, la fonction n’est pas configurée pour lever des exceptions (ErrorAction n’est pas défini sur Stop), donc Retry-CvCommand ne peut pas intercepter l’exception, et la fonction échouera trois fois.
    $sbUseCase2 ={
        param ($identity)
        get-aduser -Identity $identity
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase2 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $false
# Cas d’usage 3 : arrêt des nouvelles tentatives en cas de résultat null
# Description : la fonction Retry-CvCommand récupère la propriété 'Office' d’un utilisateur Active Directory avec l’identité fournie. Dans ce cas, l’utilisateur existe mais la propriété office est null, donc nous allons arrêter immédiatement l’exécution (stopOnNull est défini sur $true). Ce comportement est utile lorsque vous ne voulez pas continuer à réessayer si une certaine condition (résultat null) est remplie.
    $sbUseCase3 ={
        param ($identity)
        $office = get-aduser -Identity $identity -Properties Office | Select-Object Office
        return $office.Office
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase3 -params "CN=joker j,OU=OU_test,DC=contoso,DC=local" -retryCount 3 -sleepTime 1 -stopOnNull $true

• Get-CvCustomAttributes : cette fonction fournit certaines informations, telles que le type et l’attribut omSyntax d’un attribut Active Directory. La fonction nécessite deux paramètres :

1. className : Active Directory inclut un schéma par défaut avec de nombreuses classes d’objets telles que users, groups, computers, organizational units, etc. Ces objets sont connus sous le nom de « Classes » ; par exemple, nous pouvons définir la valeur « User ».
2. ldapCustomAttributesName : il s’agit du nom utilisé par les clients LDAP pour lire et écrire l’attribut, donc par exemple « costCenter ».

Exemple :

Get-CvCustomAttributes -className 'User' -ldapCustomAttributesName 'CostCenter'

• Connect-CvPnPOnlineFromCurrentConnection : se connecte à un site SharePoint Online (URL secondaire) en utilisant le contexte actuel (identifiants ou certificat) de la connexion active.

Paramètres :

• -secondaryUrl : URL complète du site cible (par exemple https://contoso.sharepoint.com/sites/marketing).
• ReturnConnection (optionnel) : lorsqu’il est présent, Connect-PnPOnline est appelé avec -ReturnConnection. La fonction renvoie l’objet de connexion PnP. Utilisez-le avec les cmdlets qui prennent en charge -Connection (par exemple Get-PnPList -Connection $conn).

Exemple :

Connect-CvPnPOnlineFromCurrentConnection -secondaryUrl https://contoso.sharepoint.com/sites/marketing

• Connect-CvSpoServiceFromCurrentConnection : initie une connexion à un autre service SharePoint Online Administration en utilisant le contexte actuel de la session active. Utilisez cette fonction plutôt que de gérer manuellement les objets d’identification.

Exemple :

Connect-CvSpoServiceFromCurrentConnection -secondaryUrl https://contoso-admin.sharepoint.com