Aide-mémoire des actions personnalisées

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

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

Exemple :

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

• Get-ServerFromDn : il 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 retourne le code iso à partir du nom d’affichage d’un pays. 

Exemple :

Get-CountryCodeFromDisplayName -displayName "Italy"

• Get-CountryDisplayNameFromCode : cette fonction retourne 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’identifiants Exchange On-Premises. Cependant, cette fonction est limitée à un seul contexte de forêt.
• Get-CvADCredential : cette fonction récupère les informations d’identifiants à partir d’une session Active Directory (AD) ouverte. Elle est limitée à un seul contexte de forêt.
• Get-CvEmailAddresses : en donnant une chaîne en entrée avec une ou plusieurs adresses email séparées par une virgule, cette fonction retourne une liste d’adresses email 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 : en donnant une valeur de type de groupe (un entier) et un email, cette fonction retourne le type, afin de savoir 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 seul caractère ‘ par deux ‘’.

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 lorsqu’il faut s’assurer que votre jeton de 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 rejouer un bloc de script plusieurs fois. Ceci 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 : c’est la commande que vous souhaitez exécuter. Elle doit être fournie sous forme de bloc de script.
2. $params : ce sont les paramètres de la commande dans le bloc de script.
3. $retryCount : c’est un paramètre optionnel qui définit le nombre de tentatives si la commande échoue. La valeur par défaut est 10.
4. $sleepTime : c’est un paramètre optionnel qui définit la durée (en secondes) pendant laquelle la fonction doit attendre avant de relancer la commande. La valeur par défaut est 3 secondes.
5. $throwException : c’est un paramètre optionnel qui indique si une exception doit être lancée lorsque la commande échoue après toutes les tentatives.
6. $stopOnNull : lorsqu'il est défini sur $true, la fonction interrompt le pattern de rappel si le résultat du bloc de script est null, même si le nombre maximum de tentatives n’a pas été atteint.

Exemples :

# Case d’utilisation 1 : Réessayer avec exception levée
# Description : La fonction Retry-CvCommand tente d’exécuter le bloc de script '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 cas, 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
# Case d’utilisation 2 : Réessayer sans gestion d’exception
# Description : La fonction Retry-CvCommand essaie d’exécuter le bloc de script 'get-aduser' trois fois pour l’identité 'fake@contoso.com' donnée. Cependant, cette fois, la fonction n’est pas configurée pour lancer des exceptions (ErrorAction non mis 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
# Case d’utilisation 3 : Arrêter la répétition sur 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 nulle donc nous pouvons arrêter immédiatement l’exécution (stopOnNull est positionné sur $true). Ce comportement est utile si vous ne souhaitez pas continuer si une condition (résultat null) est rencontrée.
    $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 des informations telles que le type et l’attribut omSyntax d’un attribut Active Directory. La fonction a besoin de 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 appelés "Classes" ; par exemple, on pourrait mettre la valeur "User".
2. ldapCustomAttributesName : c’est le nom utilisé par les clients LDAP pour lire et écrire l’attribut, par exemple “costCenter”

Exemple :

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

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

Exemple :

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

• Connect-CvSpoServiceFromCurrentConnection : initie une connexion à un autre service d’administration SharePoint Online en utilisant le contexte courant de la session active. Utilisez cette fonction au lieu de gérer manuellement les objets d’identifiants.

Exemple :

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