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.
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. 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.
Nos API utilisent des techniques optimisées pour améliorer votre efficacité, ce qui vous permet d’obtenir des résultats plus rapides avec moins d’efforts. Adoptez ces API pour simplifier l’accès à vos données et améliorer votre efficacité globale.
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.
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 sous la section Autorisations de l’API. Sélectionnez « Ajouter une autorisation » et 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.
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. Voici un guide simplifié pour vous aider à démarrer :
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.
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 des données précises, 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, vous ne voyez peut-être pas les données d’utilisation quotidiennes non facturées les plus récentes jusqu’à ce que les données d’utilisation facturées du mois précédent soient disponibles. Une fois que vous avez reçu les données d’utilisation facturées, vous pouvez ensuite récupérer toutes les données d’utilisation non facturées mises à jour à partir du début du mois.
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 de cette section). Facultatif. |
| billingPeriod | True | Chaîne | Pour obtenir l’utilisation quotidienne évaluée pour le mois actuel ou le dernier mois calendrier ou la période de facturation, utilisez « actuel » ou « dernier » (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 de 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 états possibles en fonction de vos demandes, consultez Statuses.
| 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, veillez à recevoir une réponse HTTP 200 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
Paramètres de la demande
| Nom | Inclure dans | Requis | 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 : notstarted : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez un autre appel pour vérifier l’état. en cours d’exécution : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez 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. Ne définissez pas un nombre fixe d’éléments de ligne ou de taille de fichier dans le code, car ces valeurs 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 grande partition est divisée en plusieurs fichiers, 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¤cyCode=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 de facture facturée pour les ensembles d’attributs « full » ou « basic », reportez-vous au tableau suivant. Pour en savoir plus sur ces attributs, 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 déplacement de l’API v1 à partir de v2.
Chaque nom d’attribut commence maintenant par une lettre majuscule .
unitOfMeasure est mis à jour sur Unit. Sa signification et sa valeur restent inchangées.
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. Par exemple, 0,15 est maintenant de 15 %.
rateOfCredit est maintenant CreditPercentage. Le nom et la valeur ont changé. 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.