Comprendre l’API de métadonnées Salesforce / Blogs / Perficient

L’API Salesforce Metadata est un outil puissant pour les développeurs et les administrateurs. Il permet de gérer les métadonnées Salesforce en masse ou d’automatiser les tâches de déploiement. L’API permet la récupération, le déploiement et la manipulation par programmation des composants de métadonnées. Cela le rend idéal pour les environnements dotés de pipelines CI/CD ou de besoins de personnalisation étendus. Explorons ses principales fonctionnalités, ses cas d’utilisation, ses exemples de code, ainsi que ses avantages et ses inconvénients.

Qu’est-ce que l’API de métadonnées Salesforce ?

Il permet aux développeurs de travailler avec des métadonnées dans Salesforce, notamment des objets, des champs, des mises en page et des paramètres personnalisés, entre autres composants. Contrairement aux API SOAP et REST, qui gèrent les données (enregistrements), elle est spécifiquement destinée à gérer les configurations qui définissent une instance Salesforce. Ceci est particulièrement utile pour les environnements de développement dans lesquels plusieurs organisations (telles que les sandbox) doivent être synchronisées ou pour les organisations complexes qui nécessitent des mises à jour régulières des éléments de métadonnées.

Cas d’utilisation courants de l’API de métadonnées

1. Déploiement automatisé et CI/CD : les équipes peuvent automatiser les déploiements dans différents environnements (par exemple, d’un bac à sable à une organisation de production) pour rationaliser les processus de publication.
2. Gestion groupée des métadonnées : modifiez ou créez un grand nombre de composants de métadonnées à la fois, ce qui est utile pour les mises à jour sur plusieurs objets ou champs personnalisés.
3. Intégration du contrôle de version : en déployant des métadonnées à partir du contrôle de source, vous pouvez suivre les modifications, permettant ainsi de meilleures capacités de collaboration et de restauration.
4. Synchronisation de l’environnement : maintenez la cohérence des métadonnées dans plusieurs environnements Salesforce, réduisant ainsi les erreurs et améliorant la fiabilité des tests.

Premiers pas avec l’API de métadonnées

Pour interagir avec l’API Metadata, les développeurs utilisent souvent les approches suivantes :

Salesforce CLI (sfdx) : un moyen simple d’accéder aux métadonnées via des outils de ligne de commande, parfait pour les configurations CI/CD.

Workbench : un outil en ligne qui permet de déployer et de récupérer des métadonnées sans avoir besoin de CLI.

Code Apex : pour les cas d’utilisation avancés, les développeurs peuvent créer des classes Apex pour interagir directement avec l’API, bien que cette méthode ait des limites (par exemple, la création de fichiers ZIP est restreinte).

Exemple : récupération et déploiement de métadonnées avec Salesforce CLI

La CLI Salesforce est une méthode populaire pour utiliser l’API de métadonnées car elle est simple et s’intègre bien aux pipelines CI/CD. Voici comment récupérer et déployer des métadonnées à l’aide de « sfdx ».

1. Récupérer les métadonnées Tout d’abord, créez un fichier « package.xml » qui définit les métadonnées à récupérer. Puis exécutez :

sfdx force:mdapi:retrieve r ./metadata unpackaged package.xml u <yourOrgAlias>

Cette commande extrait les composants de métadonnées de l’organisation spécifiée.

2. Déployer les métadonnées Après avoir modifié vos fichiers de métadonnées, vous pouvez les déployer sur l’organisation cible avec :

 sfdx force:mdapi:deploy d ./metadata u <yourOrgAlias> w 1

Exemple : utilisation de l’API de métadonnées dans Apex

Bien que cela soit rare en raison des limitations, vous pouvez utiliser Apex pour interagir avec l’API de métadonnées. Vous trouverez ci-dessous un exemple simple qui récupère les métadonnées des étiquettes personnalisées :

public class MetadataAPIExample {

    public static void retrieveCustomLabelMetadata(String languageCode) {

        MetadataService.MetadataPort service = createMetadataService();

        try {

            MetadataService.Translations translations =

                (MetadataService.Translations) service.readMetadata('Translations', new String[] { languageCode }).getRecords()[0];

           
            if (translations != null && translations.customLabels != null) {

                for (MetadataService.CustomLabelTranslation label : translations.customLabels) {

                    System.debug('Label: ' + label.name + ' Translation: ' + label.label);

                }

            } else {

                System.debug('No translations found for this language.');

            }

        } catch (Exception e) {

            System.debug('Error: ' + e.getMessage());

        }

    }

    private static MetadataService.MetadataPort createMetadataService() {

        MetadataService.MetadataPort service = new MetadataService.MetadataPort();

        service.SessionHeader = new MetadataService.SessionHeader_element();

        service.SessionHeader.sessionId = UserInfo.getSessionId();

        return service;

    }

}

Remarque : Cet exemple est en lecture seule en raison des limitations de l’API de métadonnées dans Apex ; la mise à jour des traductions directement à l’aide d’Apex n’est toujours pas prise en charge.

Avantages

1. Automatisation et efficacité : simplifie les tâches répétitives telles que les déploiements et la synchronisation des métadonnées, ce qui réduit les erreurs manuelles et fait gagner du temps.
2. Idéal pour les modifications importantes de métadonnées : la gestion groupée gère les modifications sur un grand nombre de composants.
3. Flexibilité avec les pipelines CI/CD : s’intègre aux outils DevOps tels que Jenkins ou GitLab, ce qui permet un développement rationalisé et des cycles de publication plus rapides.
4. Cohérence de l’environnement : maintient les environnements synchronisés, ce qui est particulièrement utile dans le développement et les tests agiles.

Inconvénients et limites

1. Compatibilité Apex limitée : bien que vous puissiez utiliser l’API de métadonnées avec Apex, certaines opérations, telles que la création de fichiers ZIP ou le déploiement de certains types de métadonnées, ne sont pas prises en charge. Par exemple, la mise à jour des traductions directement dans Apex est limitée en raison de restrictions d’insertion.
2. Complexité de la gestion XML : nécessite une utilisation intensive de fichiers XML (par exemple, « package.xml »), qui peuvent être difficiles à gérer et à déboguer, en particulier dans les grands projets.
3. Restrictions de déploiement : certains composants de métadonnées, tels que les types d’enregistrement ou les ensembles de valeurs globales, peuvent ne pas se déployer correctement si les dépendances ne sont pas correctement gérées.
4. Erreurs liées aux ensembles de métadonnées volumineux : le déploiement ou la récupération d’ensembles de métadonnées volumineux peut entraîner des délais d’attente ou des erreurs, ce qui nécessite de diviser les composants en déploiements plus petits.

Solutions de contournement pour les limitations

Étant donné que certaines limitations de l’API Metadata empêchent les mises à jour directes, comme avec les traductions d’étiquettes personnalisées, les équipes doivent souvent utiliser des solutions de contournement créatives :

1. Utiliser Salesforce CLI : la CLI fournit des fonctionnalités de déploiement fiables pour la plupart des types de métadonnées.
2. Tirer parti des solutions middleware : des outils tels que les applications Node.js ou .NET avec des bibliothèques telles que « jsforce » permettent une gestion robuste des métadonnées dans les environnements où les appels CLI ou API directs échouent.
3. Créez des scripts de déploiement personnalisés : pour les besoins de déploiement récurrents, les scripts personnalisés automatisent la récupération, la modification et le déploiement des fichiers de métadonnées.

Pensées finales

L’API Salesforce Metadata est un outil essentiel pour toute équipe gérant des organisations complexes ou plusieurs environnements. Sa capacité à gérer par programmation les composants de métadonnées rationalise les flux de travail et augmente la productivité, ce qui en fait un atout précieux dans le développement de Salesforce. Il est essentiel d’être conscient des limites de l’API de métadonnées Salesforce. Ceci est particulièrement important lorsque vous travaillez avec des types de métadonnées qui nécessitent un traitement spécial, tels que les traductions d’étiquettes personnalisées. En combinant l’API Metadata avec Salesforce CLI et les solutions middleware, les équipes peuvent relever la plupart des défis. Cette approche les aide à exploiter efficacement les capacités de métadonnées de Salesforce.

Consultez également les articles ci-dessous !

Démystifier Package.xml : conseils et bonnes pratiques pour la gestion des métadonnées Salesforce

Documentation Salesforce – API de métadonnées