API de rapprochement de facture facturée v2 (GA)

S’applique à : Espace partenaires (indisponible dans Azure Government ou Azure China 21Vianet)

Comprendre l’architecture

La nouvelle API asynchrone offre des avancées significatives dans la façon dont nous gérons l’accès aux données de facturation et de rapprochement. Cette approche résout les défis associés aux méthodes synchrones traditionnelles, telles que la gestion des connexions à longue durée de vie et le traitement de lots de données volumineux. Voici les principaux avantages et mécanismes de cette API :

Composants clés

Sécuriser l’accès avec le modèle de clé de valet

Le modèle de clé de valet offre un accès sécurisé et limité à vos données de facturation. Similaire à la façon dont une clé de valet permet à quelqu’un de conduire votre voiture sans accéder au coffre, ce modèle garantit un contrôle d’accès granulaire. Au lieu de partager des informations d’identification, un jeton de signature d’accès partagé (SAP) accorde un accès limité et limité au temps à des ressources spécifiques. Ce modèle réduit le risque d’accès non autorisé en configurant des délais d’expiration précis et des autorisations d’accès.

Efficacité améliorée par le biais d’un modèle de demande-réponse asynchrone

Considérez cela comme passer commande dans un restaurant très fréquenté. Au lieu d’attendre au comptoir, vous recevez un buzzer et pouvez faire d’autres choses pendant que votre commande est préparée. Lorsque les données sont prêtes, le système vous avertit.

La nature asynchrone de l’API signifie que vous effectuez une requête et que le système le traite en arrière-plan. Cette demande-réponse asynchrone utilise efficacement les ressources, réduit la charge du serveur et minimise les temps d'attente et les échecs fréquents avec la récupération de données synchrone.

Flexibilité des autorisations d’accès aux données

Les jetons SAP offrent une flexibilité dans la gestion des autorisations d’accès aux données. Vous pouvez générer des jetons qui accordent l’accès à tous les attributs des données de rapprochement de facture facturées ou limitent l’accès à des sous-ensembles spécifiques. Cette granularité permet aux organisations d’adapter l’accès aux données en fonction des stratégies internes et des exigences réglementaires, en améliorant la sécurité et la conformité.

Flux de travail simplifié et temps de traitement des données améliorés

Le modèle de demande-réponse asynchrone simplifie le traitement des données en autorisant l’accès dynamique au lieu de lots fixes de 2 000 éléments de ligne. Cette approche entraîne des résultats plus rapides et des temps de traitement améliorés, ce qui simplifie l’intégration des données de facturation et de rapprochement aux systèmes et workflows existants.

Avantages

1. Avantages en matière de performances

   Au lieu de conserver des connexions de longue durée et de traiter des lots fixes, le nouveau système vous permet de :

   • Effectuez une demande initiale rapide.

   • Recevez un jeton d’accès sécurisé.

   • Traitez les données à votre propre rythme.

   • Accédez exactement à ce dont vous avez besoin quand vous en avez besoin.

2. améliorations de sécurité

   Le modèle de clé de valet, implémenté par le biais de jetons SAP, fournit :

   • Accès limité dans le temps.

   • Autorisations restreintes.

   • Élimination du partage ou du stockage des informations d’identification permanentes.

   • Contrôle d’accès affiné.

3. Avantages architecturaux

   Le modèle de demande-réponse asynchrone agit comme un assistant personnel qui :

   • Prend votre requête.

   • Gère la tâche en arrière-plan.

   • Vous avertit quand tout est prêt.

Adopter des API optimisées pour améliorer les performances

L’adoption de ces API optimisées simplifie le flux de travail et améliore les performances globales dans la gestion des données. Grâce au contrôle d’accès sécurisé et aux mécanismes de récupération efficaces, vous obtenez de meilleurs résultats avec moins d’efforts, ce qui permet d’améliorer l’efficacité opérationnelle.

En conclusion, la nouvelle API asynchrone permettant d’accéder aux données de facturation et de rapprochement par le biais d’objets blob Azure est un outil puissant. Il offre un accès sécurisé et efficace aux données financières, rationalise les flux de travail, réduit les charges de serveur et améliore les temps de traitement, tous avec une sécurité et une conformité élevées.

Autoriser votre application à accéder en toute sécurité aux données de facturation des partenaires

Pour permettre à votre application d’accéder aux données de facturation des partenaires, suivez ce lien et familiarisez-vous avec les principes de base de l’authentification et de l’autorisation pour Microsoft Graph. Cette étape est cruciale, car elle garantit que votre application peut accéder en toute sécurité aux données nécessaires.

Enregistrez votre application et attribuez l’autorisation PartnerBilling.Read.All

Vous pouvez attribuer l’autorisation « PartnerBilling.Read.All » à l’aide du portail Azure ou du Centre d’administration Microsoft Entra. En effectuant ces étapes, vous vous assurez que votre application a l’accès requis aux données de facturation des partenaires. Voici comment procéder :

1. Inscrivez votre application sur la page d’accueil de Microsoft Entra sous la section Inscriptions d’applications.
2. Accordez l’autorisation nécessaire en accédant à la page de l’application Microsoft Entra. Dans la section Autorisations de l’API, sélectionnez Ajouter une autorisation et choisissez l’étendue PartnerBilling.Read.All.

En savoir plus sur les points de terminaison d’API clés

Pour vous aider à récupérer les éléments de ligne de rapprochement de facture de nouveau commerce facturés de façon asynchrone, nous proposons deux points de terminaison d’API clés. Ces points de terminaison vous aident à gérer efficacement votre processus de rapprochement des factures. Suivez ce guide simplifié pour commencer rapidement.

Utiliser le point de terminaison de rapprochement de facture facturée

Tout d’abord, utilisez cette API pour récupérer les éléments de ligne de rapprochement de facture facturée de nouveau commerce. Lorsque vous effectuez une requête, vous recevez un état HTTP 202 et un en-tête d’emplacement avec une URL. Interrogez régulièrement cette URL jusqu’à ce que vous obteniez un état de réussite et une URL de manifeste.

Utiliser le point de terminaison d’état de l’opération

Ensuite, continuez à vérifier l’état de l’opération en appelant cette API à intervalles réguliers. Si les données ne sont pas prêtes, la réponse inclut un en-tête Retry-After indiquant la durée d’attente avant de réessayer. Une fois l’opération terminée, vous recevez une ressource de manifeste avec un lien de dossier de stockage pour télécharger les données d’utilisation. La réponse segmente les fichiers pour améliorer le débit et permettre un parallélisme d’E/S.

Passer en revue le diagramme de séquence

Voici un diagramme de séquence qui montre les étapes de téléchargement des données de rapprochement des factures de nouveau commerce.

Suivez la séquence d'actions de l'utilisateur pour récupérer les données de rapprochement de factures.

Voici la séquence d’actions de l’utilisateur pour récupérer les données de rapprochement des factures publiées :

• Envoyer une demande POST
• Vérifier l’état de la demande
• Télécharger les éléments de ligne de rapprochement à partir du Stockage Blob Azure

Envoyer une requête POST

Envoyez une requête POST au point de terminaison de l’API.

Obtenir les éléments de ligne de rapprochement de facture facturée

Obtenez les éléments de ligne de rapprochement de facture facturée.

Requête d’API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Paramètres de requête

N/A

Corps de la demande

En-têtes de requête

En-têtes de requête pour l’API à l’aide des étapes répertoriées dans Meilleures pratiques pour l’utilisation de Microsoft Graph. En suivant ces instructions, vous garantissez la fiabilité et la prise en charge de votre application. Votre attention aux détails de cette étape est essentielle à une intégration transparente et à des performances optimales.

Réponse de l’API

HTTP/1.1 202 Accepted  
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

L’API répond généralement avec un état HTTP 202. Vous pouvez également rencontrer d’autres statuts en fonction de vos demandes. Ces états sont répertoriés dans la section États de réponse de l’API Standard.

Vérifier l’état de la requête

Pour suivre l’état d’une requête, vérifiez que vous recevez une réponse HTTP 200 qui est un code d’état standard indiquant « réussi » ou « échoué ». En cas de réussite, vous trouvez l’URL du manifeste dans l’attribut « resourceLocation ». Cet attribut fournit un point de terminaison pour accéder aux informations requises.

Obtenir l’état de l’opération

Récupère l’état d’une requête.

Requête d’API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Paramètres de requête

En-tête de requête

En-têtes de requête pour l’API à l’aide des étapes répertoriées dans Meilleures pratiques pour l’utilisation de Microsoft Graph. En suivant ces instructions, vous garantissez la fiabilité et la prise en charge de votre application. Votre attention aux détails de cette étape est essentielle à une intégration transparente et à des performances optimales.

Corps de la demande

N/A.

État de la réponse

Outre les états HTTP standard répertoriés dans États de réponse de l’API Standard, l’API peut également retourner l’état HTTP suivant :

Charge utile de la réponse

La charge utile de la réponse de l’API inclut les attributs suivants :

Objet d’emplacement de la ressource

Requête d’API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

La réponse recommande d’attendre 10 secondes avant de réessayer lorsque vos données sont en cours de traitement.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Requête d’API

(10 secondes après la requête précédente...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

L’API retourne l’état « succeeded » et l’URI de « resourceLocation ».

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

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Télécharger les éléments de ligne de rapprochement à partir du Stockage Blob Azure

Tout d’abord, vous devez obtenir le jeton de signature d’accès partagé (SAS) et l’emplacement de stockage blob. Recherchez ces détails dans les propriétés sasToken et rootDirectory de la réponse de l’API de charge utile du manifeste.

Pour continuer, procédez comme suit :

1. Téléchargez le fichier blob à l’aide du kit de développement logiciel (SDK)/outil stockage Azure .
2. Décompressez le fichier, qui se trouve au format JSONLines.

États de réponse de l’API Standard

Vous pouvez obtenir les états HTTP suivants à partir de la réponse de l’API :

Comparer les attributs de rapprochement de facture de base et complète

Pour comparer les attributs retournés par l’API de rapprochement de facture facturée pour les ensembles d’attributs « full » ou « basic », reportez-vous à ce tableau. Pour en savoir plus sur ces attributs et leurs significations, consultez Utiliser le fichier de rapprochement.

Exemple de code

Si vous avez besoin d’aide pour migrer vers cette API, reportez-vous au lien qui inclut l’exemple de code C#.

Exemples d’API pour obtenir des données de rapprochement de facturation à partir de l’Espace partenaires.

Contenu associé

• Outil ou SDK Stockage Azure
• Utiliser l’API Microsoft Graph pour exporter les données de facturation des partenaires