Partage via


API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA)

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

Notre nouvelle API asynchrone offre un moyen plus rapide et plus efficace d’accéder à vos données de facturation et de rapprochement via des objets blob Azure. Au lieu de conserver une connexion ouverte pendant des heures ou de traiter des lots de 2 000 éléments de ligne, vous pouvez maintenant simplifier votre flux de travail, réduire la charge du serveur et améliorer les temps de traitement des données.

Les nouvelles API de rapprochement d’utilisation évaluées par le commerce utilisent des techniques avancées telles que la clé de valet et les modèles de demande-réponse asynchrones. Le modèle de clé de valet permet un accès sécurisé aux ressources sans partager les informations d’identification, tandis que le modèle de demande-réponse asynchrone permet une communication efficace entre les systèmes.

Ces API vous fournissent un jeton de signature d’accès partagé (SAP) que vous pouvez utiliser pour accéder à tous les attributs ou à un sous-ensemble des données de rapprochement d’utilisation évaluées quotidiennement. Ce jeton améliore la sécurité en accordant un accès à temps limité et offre une flexibilité dans la gestion des autorisations d’accès aux données.

En adoptant nos API optimisées, vous pouvez obtenir des résultats plus rapides avec moins d’efforts, simplifier l’accès aux données et améliorer l’efficacité globale. Adoptez ces outils pour simplifier votre flux de travail et gérer les autorisations plus efficacement.

Remarque

Les nouvelles API ne sont pas hébergées sur l’hôte de l’API de l’Espace partenaires. Au lieu de cela, vous pouvez les trouver sur MS Graph à l’aide de l’API Microsoft Graph pour exporter les données de facturation des partenaires - Microsoft Graph v1.0 | Microsoft Learn. Pour accéder à ces API, reportez-vous aux détails suivants.

Vous ne pouvez utiliser ces API pour le cloud public/mondial MS Graph que maintenant. Ils ne sont pas encore disponibles pour Azure Government ou Azure China 21Vianet.

Important

Pour autoriser l’accès à votre application 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.

Vous pouvez attribuer l’autorisation « PartnerBilling.Read.All » à l’aide du Portail Azure ou du Centre d’administration Entra. Voici comment procéder :

  • Inscrivez votre application sur la page d’accueil de Microsoft Entra sous la section Inscriptions d’applications.
  • Pour accorder l’autorisation nécessaire, accédez à la page Microsoft Entra App. Dans la section Autorisations de l’API, sélectionnez « Ajouter une autorisation », puis choisissez l’étendue « PartnerBilling.Read.All ».

En effectuant ces étapes, vous vérifiez que votre application dispose de l’accès requis aux données de facturation des partenaires.

Remarque

Si vous avez utilisé notre version bêta, vous trouverez probablement la transition vers la version de disponibilité générale lisse et intuitive. Pour vous aider à comprendre les mises à jour et les améliorations, nous vous recommandons de comparer les versions bêta et ga. La compréhension de ces mises à jour vous aidera à optimiser les nouvelles fonctionnalités et améliorations disponibles dans la version en disponibilité générale.

Important

La nouvelle utilisation quotidienne du commerce n’inclut pas les frais pour ces produits :

  • Réservation Azure
  • Plan d’épargne Azure
  • Office
  • Dynamics
  • Microsoft Power Apps
  • Logiciels perpétuels
  • Abonnement logiciel
  • Produit SaaS non Microsoft ou marketplace

Présentation de l’API

Pour vous aider à récupérer les nouveaux éléments de ligne d’utilisation facturés quotidiennement au commerce , nous proposons deux points de terminaison d’API clés. Suivez ce guide simplifié pour commencer rapidement et efficacement !

Point de terminaison de ligne d’utilisation

Tout d’abord, utilisez cette API pour récupérer les nouveaux éléments de ligne d’utilisation quotidiens du 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.

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.

En suivant ces étapes, vous pouvez gérer efficacement votre processus de rapprochement de facture.

Diagramme de séquence

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

Diagramme montrant les étapes de téléchargement de la rapprochement.

Séquence d’actions utilisateur

Pour récupérer les nouveaux éléments de ligne de rapprochement d’utilisation évalués quotidiennement par le commerce , procédez comme suit :

Étape 1 : Envoyer une demande

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

Obtenir des éléments de ligne d’utilisation non facturés tous les jours

Obtenez de nouveaux éléments de ligne d’utilisation quotidiens non facturés pour le mois ou le dernier mois calendrier ou la période de facturation.

Remarque

Vous pouvez accéder à vos éléments de ligne d’utilisation quotidiens non facturés via l’API ou le portail de l’Espace partenaires. Pour garantir la précision des données, autorisez jusqu’à 24 heures de disponibilité. Selon votre emplacement et lorsque les compteurs signalent l’utilisation, il peut y avoir d’autres retards.

Nous hiérarchisons d’abord la remise du temps des données d’utilisation facturées par jour. Parfois, les plus récentes données d’utilisation non facturées quotidiennes peuvent ne pas apparaître tant que les données facturées du mois précédent ne sont pas disponibles. Une fois que vous avez reçu les données facturées, vous pouvez accéder à toutes les données d’utilisation non facturées mises à jour à partir du début du mois.

points clés:

  • Prévoyez jusqu'à 24 heures pour la disponibilité des données.
  • Il peut y avoir des retards supplémentaires en fonction de votre emplacement et des délais de transmission des mesures par le compteur.
  • Les données d’utilisation facturées par jour sont classées par ordre de priorité par rapport aux données non facturées.

Votre compréhension et votre patience sont appréciées, car nous nous efforçons de fournir les informations les plus précises et les plus rapides possibles.

Requête d’API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}
Corps de la demande
Attribut Obligatoire Type Description
attributeSet False Chaîne Choisissez « full » pour tous les attributs ou « de base » pour un ensemble limité. S’il n’est pas spécifié, « full » est la valeur par défaut. Consultez la liste des attributs dans cette section. Facultatif.
billingPeriod True Chaîne Pour obtenir une utilisation quotidienne non facturée, utilisez « actuel » pour la période de facturation actuelle ou « dernière » pour la période de facturation précédente (identique à « précédent » dans l’API v1). Obligatoire.
currencyCode True Chaîne Code monétaire de facturation du partenaire. Obligatoire.
En-têtes de requête

Pour demander des en-têtes pour l’API, consultez Fiabilité et prise en charge.

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 états en fonction de vos demandes. Ces états sont répertoriés dans la section États de réponse de l’API Standard.

Code Description
202 – Accepté Votre demande a été acceptée. Pour vérifier l’état de votre demande, interrogez l’URL fournie dans l’en-tête d’emplacement.

Obtenir les éléments de ligne d’utilisation facturés tous les jours

Obtenez les nouveaux éléments de ligne d’utilisation facturés quotidiennement pour une facture pour la période de facturation fermée.

Requête d’API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Paramètres de requête

S/O

Corps de la demande
Attribut Obligatoire Type Description
invoiceId True Chaîne Identificateur unique pour chaque facture. Obligatoire.
attributeSet False Chaîne Choisissez « full » pour tous les attributs ou « de base » pour un ensemble limité. S’il n’est pas spécifié, « full » est la valeur par défaut. Consultez la liste des attributs dans cette section. Facultatif.
En-tête de requête

En-têtes de requête pour l’API. Pour en savoir plus, consultez la fiabilité et la prise en charge.

Réponse de l’API

HTTP/1.1 202 Accepté
Emplacement : https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Lorsque vous utilisez l’API, elle retourne généralement un état HTTP 202. Pour obtenir d’autres statuts possibles en fonction de vos demandes, consultez Statuts.

Code Description
202 – Accepté Votre demande a été acceptée. Pour vérifier l’état de votre demande, interrogez l’URL fournie dans l’en-tête d’emplacement.

Étape 2 : Vérifier l’état de la demande

Pour suivre l’état d’une demande, vérifiez que vous recevez une réponse HTTP 200 qui est un code d’état standard indiquant « réussi » ou « échoué ». Si elle réussit, 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 demande.

Requête d’API

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

Paramètres de la demande
Nom Inclure dans Obligatoire Type Description
operationId URI de demande True Chaîne Identificateur unique pour vérifier l’état de la demande. Obligatoire.
En-tête de requête

Pour demander des en-têtes pour l’API, consultez Fiabilité et prise en charge.

Corps de la demande

N/A.

État de la réponse

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

Code Description
410 - Disparu Le lien manifeste expire après une heure définie. Pour obtenir à nouveau le lien manifeste, envoyez une nouvelle requête.
Charge utile de réponse

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

Attribut Obligatoire Description
id True Identificateur unique pour chaque réponse. Obligatoire.
statut True Valeurs et actions : Obligatoire :

pas de démarrage : attendez la durée spécifiée dans l’en-tête « Réessayer-Après », puis effectuez un autre appel pour vérifier l’état.

en cours d’exécution : attendez la durée spécifiée dans l’en-tête « Réessayer-Après », puis passez un autre appel pour vérifier l’état.

réussite : les données sont prêtes. Récupérez la charge utile du manifeste à l’aide de l’URI spécifié dans resourceLocation.

échec : l’opération a échoué définitivement. Redémarrez-le.
createdDateTime True Heure à laquelle la demande a été faite. Obligatoire.
lastActionDateTime True La dernière fois que l’état a changé. Obligatoire.
resourceLocation False URI de la charge utile du manifeste. Facultatif.
error False Détails sur les erreurs fournies au format JSON.
Facultatif.
Attributs inclus :
message : Description de l’erreur.
code : type d’erreur.
Objet Resource Location
Attribut Description
id Identificateur unique du manifeste.
schemaVersion Version du schéma de manifeste.
dataFormat Format du fichier de données de facturation.

compresséJSON : format de données où chaque objet blob est un fichier compressé qui contient des données au format de lignes JSON . Pour récupérer les données de chaque objet blob, décompressez-les.
createdDateTime Date et heure de création du fichier manifeste.
eTag Version des données du manifeste. Une modification des informations de facturation génère une nouvelle valeur.
partnerTenantId ID Microsoft Entra du locataire du partenaire.
rootDirectory Répertoire racine du fichier.
sasToken Jeton SAP (signature d’accès partagé) qui vous permet de lire tous les fichiers sous le répertoire.
partitionType Divise les données en plusieurs objets blob en fonction de l’attribut « partitionValue ». Le système fractionne les partitions qui dépassent le nombre pris en charge. Par défaut, les données sont partitionnée en fonction du nombre d’éléments de ligne dans le fichier. Évitez les nombres d’éléments de ligne de codage en dur ou les tailles de fichier, car ils peuvent changer.
blobCount Nombre total de fichiers pour cet ID de locataire partenaire.
blobs Tableau JSON d’objets « blob » qui contiennent les détails du fichier pour l’ID de locataire partenaire.
objet blob Objet contenant les détails suivants : nom et partitionValue
name Le nom de l’objet Blob.
partitionValue Partition qui contient le fichier. La partition volumineuse est divisée en plusieurs fichiers en fonction de certains critères, tels que la taille de fichier ou le nombre d’enregistrements, chaque fichier contenant le même « partitionValue ».
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 lors du traitement des données.

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 demande 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 « réussi » 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"

            }

        \]

    }

}

Étape 3 : Télécharger les éléments de ligne de rapprochement d’utilisation évalués quotidiennement à partir du stockage Blob Azure

Tout d’abord, vous devez obtenir le jeton de signature d’accès partagé (SAP) et l’emplacement de stockage d’objets blob. Vous trouverez ces détails dans les propriétés « sasToken » et « rootDirectory » de la réponse de l’API de charge utile du manifeste. Ensuite, pour télécharger et décompresser le fichier blob, utilisez le kit sdk/outil Stockage Azure. Il est au format JSONLines .

Conseil

Veillez à consulter notre exemple de code. Il vous montre comment télécharger et décompresser le fichier blob Azure dans votre base de données locale.

États de réponse de l’API standard

Vous pouvez recevoir ces états HTTP à partir de la réponse de l’API :

Code Description
400 Demande incorrecte. La demande est manquante ou contient des données incorrectes. Recherchez les détails de l’erreur dans le corps de la réponse.
401 - Non autorisé L’authentification est requise avant d’effectuer le premier appel. Authentifiez-vous auprès du service d’API partenaire.
403 - Interdit Vous n’avez pas l’autorisation nécessaire pour effectuer la demande.
404 - Non trouvé Les ressources demandées ne sont pas disponibles avec les paramètres d’entrée fournis.
410 - Disparu Le lien manifeste n’est plus valide ou actif. Envoyez une nouvelle demande.
500 - Erreur interne du serveur L’API ou ses dépendances ne peuvent pas répondre à la demande pour le moment. Réessayez plus tard.
5000 – Aucune donnée disponible Le système n’a pas de données pour les paramètres d’entrée fournis.

Comparer les versions bêta et ga

Consultez le tableau de comparaison pour voir les différences entre la version bêta et les versions en disponibilité générale. Si vous utilisez actuellement la version bêta, la transition vers la version ga est simple et facile.

Informations importantes Bêta Disponibilité générale
Point de terminaison de l’hôte d’API https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
Méthode HTTP POST POST
Point de terminaison de l’API d’utilisation quotidienne non facturé https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Paramètres d’entrée pour l’API d’utilisation quotidienne non facturée Pour spécifier des paramètres dans la requête d’API, incluez-les dans la chaîne de requête de l’URL de la requête.
Par exemple, pour spécifier les paramètres period et currencyCode, ajoutez ?period=current&currencyCode=usd à l’URL de la requête.
Pour fournir des entrées, incluez un objet JSON dans le corps de la requête. Votre json doit avoir les propriétés suivantes :
* currencyCode : votre devise de facturation. Par exemple, USD.
* billingPeriod : période de facturation de la facture. Par exemple, en cours.
Voici un exemple d’objet JSON qui inclut les propriétés currencyCode et billingPeriod :<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}
Point de terminaison de l’API d’utilisation facturé par jour https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
Paramètres d’entrée pour l’API d’utilisation quotidienne facturée Pour spécifier des paramètres dans la requête d’API, incluez l’ID de facture dans l’URL de la requête. En outre, vous pouvez inclure un paramètre de fragment facultatif dans la chaîne de requête pour récupérer l’ensemble complet d’attributs.
Par exemple, pour récupérer l’ensemble complet d’attributs, ajoutez ?fragment=full à l’URL de la requête.
Pour fournir des entrées, incluez un objet JSON dans le corps de la requête. Votre json doit avoir les propriétés suivantes :
* invoiceId : identificateur unique de la facture. Par exemple, G00012345.
* attributeSet : attributs qui doivent être dans la réponse, comme complet.
Voici un exemple d’objet JSON qui inclut les propriétés invoiceId et attributeSet :
{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}
Ressource de manifeste Utilisez une méthode GET /manifests/{id} distincte pour récupérer la ressource de manifeste. Utilisez la méthode GET /operations/{Id} pour accéder à la ressource manifeste dans resourceLocation. Cette méthode permet de gagner du temps en éliminant la nécessité d’un appel distinct à GET /manifests/{id}.
Modifications apportées au schéma de manifeste
« id » : Non disponible « id » : identificateur unique de la ressource de manifeste.
« version » : Disponible « version » : remplacé par « schemaversion ».
« dataFormat » : disponible « dataFormat » : disponible.
« utcCretedDateTime » : Disponible « utcCretedDateTime » : remplacé par « createdDateTime ».
« eTag » : Disponible « eTag » : disponible.
« partnerTenantId » : Disponible « partnerTenantId » : Disponible
« rootFolder » : disponible « rootFolder » : remplacé par « rootDirectory ».
« rootFolderSAS » : disponible « rootFolderSAS » : remplacé par « sasToken ». Cette mise à jour fournit uniquement le jeton sans le chemin du répertoire racine. Pour localiser le répertoire, utilisez la propriété « rootDirectory » à la place.
« partitionType » : Disponible « partitionType » : disponible.
« blobCount » : disponible « blobCount » : disponible.
« sizeInBytes » : Disponible « sizeInBytes » : non disponible.
« objets blob » : disponible « objets blob » : disponible.
« objet blob » : disponible « objet blob » : disponible.
« name » : Disponible « name » : Disponible.
« partitionValue » : Disponible « partitionValue » : disponible.

Attributs quotidiens de l’élément de ligne de rapprochement de l’utilisation

Pour comparer les attributs retournés par l’API de rapprochement d’utilisation facturée ou non facturée pour les ensembles d’attributs « complets » ou « de base », reportez-vous à ce tableau. Pour en savoir plus sur ces attributs et leurs significations, consultez cette documentation .

Attribut COMPLET De base
PartnerId Oui Oui
PartnerName Oui Oui
CustomerId Oui Oui
CustomerName Oui Oui
CustomerDomainName Oui non
CustomerCountry Oui non
MpnId Oui non
Tier2MpnId Oui non
InvoiceNumber Oui Oui
ProductId Oui Oui
SkuId Oui Oui
AvailabilityId Oui non
SkuName Oui Oui
ProductName Oui non
PublisherName Oui Oui
PublisherId Oui non
SubscriptionDescription Oui non
SubscriptionId Oui Oui
ChargeStartDate Oui Oui
ChargeEndDate Oui Oui
UsageDate Oui Oui
MeterType Oui non
MeterCategory Oui non
MeterId Oui non
MeterSubCategory Oui non
MeterName Oui non
MeterRegion Oui non
Unité Oui Oui
ResourceLocation Oui non
ConsumedService Oui non
ResourceGroup Oui non
ResourceURI Oui Oui
ChargeType Oui Oui
UnitPrice Oui Oui
Quantité Oui Oui
UnitType Oui non
BillingPreTaxTotal Oui Oui
BillingCurrency Oui Oui
PricingPreTaxTotal Oui Oui
PricingCurrency Oui Oui
ServiceInfo1 Oui non
ServiceInfo2 Oui non
Étiquettes Oui non
AdditionalInfo Oui non
EffectiveUnitPrice Oui Oui
PCToBCExchangeRate Oui Oui
PCToBCExchangeRateDate Oui non
EntitlementId Oui Oui
EntitlementDescription Oui non
PartnerEarnedCreditPercentage Oui non
CreditPercentage Oui Oui
CreditType Oui Oui
BenefitOrderID Oui Oui
BenefitID Oui non
BenefitType Oui Oui

Important

Notez ces modifications lors du passage de l’API v1 à v2.

  • Chaque nom d’attribut commence maintenant par une lettre majuscule pour maintenir la cohérence avec le fichier et améliorer la lisibilité.

  • unitOfMeasure est mis à jour sur Unit. Sa signification et sa valeur restent inchangées, ce qui simplifie le nom de l’attribut.

  • resellerMpnId est maintenant Tier2MpnId. La signification et la valeur sont identiques.

  • rateOfPartnerEarnedCredit est mis à jour vers PartnerEarnedCreditPercentage. Le nouveau nom et la nouvelle valeur reflètent désormais le pourcentage au lieu de la fraction, ce qui facilite la compréhension. Par exemple, 0,15 est maintenant de 15 %.

  • rateOfCredit est maintenant CreditPercentage. Le nom et la valeur ont été modifiés afin de fournir une compréhension plus claire. Par exemple, 1,00 est maintenant 100 %.

Nous pensons que ces modifications rendent les API plus intuitives et plus faciles à utiliser.

Exemple de code

Pour utiliser cette API, consultez le lien suivant, qui inclut l’exemple de code C#.

Exemples d’API de l’Espace partenaires : obtenir des données de reconquête de facturation.