Contenu de l’objet blob de requête

Article
02/07/2024

L’opération Query Blob Contents applique une instruction langage SQL simple (SQL) sur le contenu d’un objet blob et retourne uniquement le sous-ensemble interrogé des données. Vous pouvez également appeler Query Blob Contents pour interroger le contenu d’une version ou d’une instantané.

Requête

Vous pouvez construire la Query Blob Contents requête comme suit. Nous recommandons HTTPS. Remplacez myaccount par le nom de votre compte de stockage.

URI de requête de méthode POST	Version HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&versionid=<DateTime>`	HTTP/1.0 HTTP/1.1

Paramètres URI

Vous pouvez spécifier les paramètres supplémentaires suivants dans l’URI de requête :

Paramètre	Description
`snapshot`	facultatif. Le paramètre instantané est une valeur opaque`DateTime`. Lorsqu’il est présent, il spécifie l’objet blob instantané à interroger. Pour plus d’informations sur l’utilisation des instantanés d’objets blob, consultez Créer un instantané d’un objet blob.
`versionid`	Facultatif, version 2019-12-12 et ultérieure. Le `versionid` paramètre est une valeur opaque `DateTime` . Lorsqu’il est présent, il spécifie la version de l’objet blob à récupérer.
`timeout`	facultatif. Le paramètre `timeout` est exprimé en secondes. Pour plus d’informations, consultez Définir des délais d’expiration pour les opérations de stockage Blob.

En-têtes de requête

Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs :

En-tête de requête	Description
`Authorization`	Obligatoire. Spécifie le schéma d'authentification, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`Date` ou `x-ms-date`	Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`x-ms-version`	Obligatoire pour toutes les demandes authentifiées, facultatif pour les demandes anonymes. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
`Content-Type`	Obligatoire. La valeur de cet en-tête doit être `application/xml; charset=UTF-8`.
`x-ms-lease-id:<ID>`	facultatif. Si cet en-tête est spécifié, l'opération sera exécutée uniquement si les deux conditions suivantes sont remplies : - Le bail de l’objet blob est actuellement actif. - L’ID de bail spécifié dans la demande correspond à celui de l’objet blob. Si cet en-tête est spécifié et que ces deux conditions ne sont pas remplies, la demande échoue et l'opération `Query Blob Contents` échoue avec le code d'état 412 (Échec de la précondition).
`Origin`	facultatif. Spécifie l'origine à partir de laquelle la demande est émise. La présence de cet en-tête entraîne des en-têtes CORS (Cross-Origin Resource Sharing) sur la réponse.
`x-ms-client-request-id`	facultatif. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes que le serveur reçoit.

Cette opération prend également en charge l’utilisation d’en-têtes conditionnels pour interroger le contenu de l’objet blob uniquement si une condition spécifiée est remplie. Pour plus d’informations, consultez Spécifier des en-têtes conditionnels pour les opérations de stockage Blob.

Corps de la demande

Le corps de la demande pour cette version de Query Blob Contents utilise le format XML suivant :

<?xml version="1.0" encoding="utf-8"?>  
<QueryRequest>
  <QueryType>String</QueryType>
  <Expression>String</Expression>
  <InputSerialization>
    <Format>
      <Type>String</Type>
          <DelimitedTextConfiguration>
            <ColumnSeparator>String</ColumnSeparator>
            <FieldQuote>String</FieldQuote>
            <RecordSeparator>String</RecordSeparator>
            <EscapeChar>String</EscapeChar>
            <HasHeaders>Boolean</HasHeaders>
          </DelimitedTextConfiguration>
          <JsonTextConfiguration>
            <RecordSeparator>String</RecordSeparator>
          </JsonTextConfiguration>
    </Format>
  </InputSerialization>
  <OutputSerialization>
    <Format>
      <Type>String</Type>
      <DelimitedTextConfiguration>
        <ColumnSeparator>String</ColumnSeparator >
        <FieldQuote>String</FieldQuote >
        <RecordSeparator>String</RecordSeparator>
        <EscapeChar>String</EscapeChar>
        <HasHeaders>Boolean</HasHeaders>
      </DelimitedTextConfiguration>
      <JsonTextConfiguration>
        <RecordSeparator>String</RecordSeparator>
      </JsonTextConfiguration>
      <ArrowConfiguration>
        <Schema>
            <Field>
                <Type>String</Type>
                <Name>String</Name>
            </Field>
            <Field>
                <Type>String</Type>
            </Field>
                .
                .
                .
            <Field>
                <Type>String</Type>
                <Precision>Integer</Precision>
                <Scale>Integer</Scale>
            </Field>
        </Schema>
      </ArrowConfiguration>
    </Format>
  </OutputSerialization>
</QueryRequest>

Le tableau suivant décrit les éléments du corps de la demande :

Nom de l'élément	Description
`QueryRequest`	Obligatoire. Regroupe l’ensemble des paramètres de requête.
`QueryType`	Obligatoire. Indique le type de l’expression de requête fournie. La seule valeur valide pour la version actuelle est `SQL`.
`Expression`	Obligatoire. Indique l’expression de requête dans SQL. La taille maximale de l’expression de requête est de 256 Kio. Pour plus d’informations sur la syntaxe d’expression, consultez Accélération des requêtes : informations de référence sur le langage SQL.
`InputSerialization`	facultatif. Regroupe les paramètres relatifs à la sérialisation d’entrée du contenu de l’objet blob. Si elle n’est pas spécifiée, la configuration du texte délimité est utilisée.
`Format`	Obligatoire si `InputSerialization` est spécifié. Regroupe les paramètres relatifs au format des données blob.
`Type`	Obligatoire si `InputSerialization` est spécifié. Indique le type de format. Les valeurs correctes sont `delimited`, `csv` et `json`.
`DelimitedTextConfiguration`	facultatif. Regroupe les paramètres utilisés pour interpréter les données d’objet blob si l’objet blob est mis en forme avec du texte délimité.
`ColumnSeparator`	facultatif. Indique la chaîne utilisée pour séparer les colonnes.
`FieldQuote`	facultatif. Indique la chaîne utilisée pour citer un champ spécifique.
`RecordSeparator`	facultatif. Indique la chaîne utilisée pour séparer les enregistrements.
`EscapeChar`	facultatif. Indique la chaîne utilisée comme caractère d’échappement.
`HasHeaders`	facultatif. Spécifie une valeur booléenne qui indique si les données ont des en-têtes.
`JsonTextConfiguration`	facultatif. Regroupe les paramètres utilisés pour interpréter les données d’objet blob si l’objet blob est au format JSON.
`RecordSeparator`	facultatif. Indique la chaîne utilisée pour séparer les enregistrements.
`OutputSerialization`	facultatif. Indique le format de sérialisation du contenu filtré de l’objet blob retourné dans la réponse. Si elle n’est pas spécifiée, la configuration du texte délimité est utilisée.
`Format`	Obligatoire si `OutputSerialization` est spécifié. Regroupe les paramètres concernant le format de la réponse retournée.
`Type`	Obligatoire si `OutputSerialization` est spécifié. Indique le type de format. Les valeurs valides sont `delimited`, `csv`, `json` et `arrow`.
`DelimitedTextConfiguration`	facultatif. Regroupe les paramètres utilisés pour la mise en forme de la réponse si la réponse doit être mise en forme avec du texte délimité.
`ColumnSeparator`	facultatif. Indique la chaîne utilisée pour séparer les colonnes.
`FieldQuote`	facultatif. Indique la chaîne utilisée pour citer un champ spécifique.
`RecordSeparator`	facultatif. Indique la chaîne utilisée pour séparer les enregistrements.
`EscapeChar`	facultatif. Indique la chaîne utilisée comme caractère d’échappement.
`HasHeaders`	facultatif. Spécifie une valeur booléenne qui indique si les données ont des en-têtes.
`JsonTextConfiguration`	facultatif. Regroupe les paramètres utilisés pour la mise en forme de la réponse si la réponse doit être au format JSON.
`RecordSeparator`	facultatif. Indique la chaîne utilisée pour séparer les enregistrements.
`ArrowConfiguration`	facultatif. Regroupe les paramètres utilisés pour la mise en forme de la réponse si la réponse doit être mise en forme de flèche.
`Schema`	Obligatoire si `ArrowConfiguration` est spécifié. Regroupe les paramètres concernant le schéma de la réponse Arrow retournée.
`Field`	facultatif. Regroupe les paramètres relatifs à un champ spécifique.
`Type`	Obligatoire si `Field` est spécifié. Indique le type de champ. Les valeurs valides sont `Int`, `Float`, `Decimal` et `Bool`.
`Precision`	facultatif. Indique la précision du champ.
`Scale`	facultatif. Indique l’échelle du champ.

response

La réponse inclut un code d'état HTTP, un ensemble d'en-têtes de réponse et le corps de réponse. Le corps de la réponse est au format binaire Avro. Étant donné que la longueur du contenu de la réponse est inconnue, la réponse est diffusée avec un encodage segmenté.

Code d’état

Si la requête est correctement formée et autorisée, l’opération retourne status code 202 (accepté). Les erreurs ou les messages de progression rencontrés pendant la diffusion en continu de la réponse sont retournés dans le corps de la réponse.

Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse peut également inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

Syntaxe	Description
`Last-Modified`	Indique la date/heure de la dernière modification de l’objet blob. Le format de date est conforme à la RFC 1123. Toute opération qui modifie l'objet blob, notamment une mise à jour des métadonnées ou des propriétés de l'objet blob, modifie l'heure de la dernière modification de l'objet blob.
`Content-Type`	Spécifie le format dans lequel les résultats sont renvoyés. Actuellement, cette valeur est `avro/binary`.
`ETag`	Contient une valeur que vous pouvez utiliser pour effectuer des opérations de manière conditionnelle. Pour plus d’informations, consultez Spécifier des en-têtes conditionnels pour les opérations de stockage Blob. Si la version de la demande est 2011-08-18 ou version ultérieure, la `ETag` valeur est entre guillemets.
`Content-Encoding`	Retourne la valeur qui a été spécifiée pour l’en-tête de `Content-Encoding` requête.
`Content-Language`	Retourne la valeur qui a été spécifiée pour l’en-tête de `Content-Language` requête.
`Cache-Control`	Retourné si cet en-tête a été spécifié précédemment pour l’objet blob.
`Content-Disposition`	Retourné pour les demandes effectuées avec la version du 15/08/2013 ou les versions ultérieures. Cet en-tête retourne la valeur qui a été spécifiée pour l'en-tête `x-ms-blob-content-disposition`. Le `Content-Disposition` champ d’en-tête de réponse transmet des informations supplémentaires sur la façon de traiter la charge utile de réponse. Vous pouvez également utiliser le champ d’en-tête de réponse pour joindre des métadonnées supplémentaires. Par exemple, si le champ d’en-tête de réponse est défini sur `attachment`, l’agent utilisateur ne doit pas afficher la réponse. Au lieu de cela, elle doit afficher une boîte de dialogue Enregistrer sous avec un nom de fichier autre que le nom d’objet blob spécifié.
`x-ms-blob-type: <BlockBlob>`	Retourne le type de l'objet blob.
`x-ms-request-id`	Identifie de manière unique la demande qui a été effectuée. Vous pouvez l’utiliser pour résoudre les problèmes liés à la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
`x-ms-version`	Indique la version de Stockage Blob Azure utilisée pour exécuter la demande. Inclus pour les demandes effectuées à l’aide de la version 2009-09-19 et ultérieure. Cet en-tête est également retourné pour les requêtes anonymes sans version spécifiée, si le conteneur a été marqué pour l’accès public à l’aide de la version 2009-09-19 du Stockage Blob.
`Date`	Valeur de date/heure UTC qui indique l’heure à laquelle le service a envoyé la réponse.
`Access-Control-Allow-Origin`	Retourné si la demande inclut un en-tête `Origin` et le partage de ressources cross-origine (CORS) est activé avec une règle de correspondance. Cet en-tête retourne la valeur de l'en-tête de demande d'origine en cas de correspondance.
`Access-Control-Expose-Headers`	Retourné si la demande inclut un en-tête `Origin` et le partage de ressources cross-origine (CORS) est activé avec une règle de correspondance. Cet en-tête retourne la liste des en-têtes de réponse qui seront exposés au client ou à l’émetteur de la demande.
`Vary`	Retourné avec la valeur de l'en-tête `Origin` lorsque des règles CORS sont spécifiées. Pour plus d’informations, consultez Prise en charge de CORS pour stockage Azure.
`Access-Control-Allow-Credentials`	Retourné si la requête inclut un `Origin` en-tête et que CORS est activé avec une règle de correspondance qui n’autorise pas toutes les origines. Cet en-tête est défini sur `true`.
`x-ms-blob-committed-block-count`	Indique le nombre de blocs validés présents dans l’objet blob. Cet en-tête est retourné uniquement pour les objets blob d’ajout.
`x-ms-server-encrypted: true/false`	Version 2015-12-11 ou ultérieure. La valeur de cet en-tête est définie `true` sur si les données blob et les métadonnées d’application sont entièrement chiffrées via l’algorithme spécifié. Lorsque l’objet blob n’est pas chiffré ou si seules certaines parties des métadonnées de l’objet blob/de l’application sont chiffrées, la valeur est définie sur `false`.

Response body

Le corps de la réponse contient le contenu filtré de l’objet blob envoyé sous la forme d’une série de messages au format binaire Avro. Il utilise le schéma suivant :

{
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.resultData",
    "doc": "Holds result data in the format specified for this query (CSV, JSON, etc.).",
    "fields": [
      {
        "name": "data",
        "type": "bytes"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.error",
    "doc": "An error that occurred while processing the query.",
    "fields": [
      {
        "name": "fatal",
        "type": "boolean",
        "doc": "If true, this error prevents further query processing.  More result data may be returned, but there is no guarantee that all of the original data will be processed.  If false, this error does not prevent further query processing."
      },
      {
        "name": "name",
        "type": "string",
        "doc": "The name of the error"
      },
      {
        "name": "description",
        "type": "string",
        "doc": "A description of the error"
      },
      {
        "name": "position",
        "type": "long",
        "doc": "The blob offset at which the error occurred"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.progress",
    "doc": "Information about the progress of the query",
    "fields": [
      {
        "name": "bytesScanned",
        "type": "long",
        "doc": "The number of bytes that have been scanned"
      },
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.end",
    "doc": "Sent as the final message of the response, indicating that all results have been sent.",
    "fields": [
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  }
]

Exemple de réponse

      "StatusCode": 200,
      "ResponseHeaders": {
        "Content-Type": "avro/binary",
        "Date": "Fri, 24 Apr 2020 20:25:42 GMT",
        "ETag": "\u00220x8D7E88DA9C0A75B\u0022",
        "Last-Modified": "Fri, 24 Apr 2020 20:25:43 GMT",
        "Transfer-Encoding": "chunked",
        "x-ms-blob-type": "BlockBlob",
        "x-ms-client-request-id": "f6d1983c-55e5-9f95-6d3d-80d74862d99e",
        "x-ms-creation-time": "Fri, 24 Apr 2020 20:25:43 GMT",
        "x-ms-lease-state": "available",
        "x-ms-lease-status": "unlocked",
        "x-ms-request-id": "46c09ab1-b01e-0001-1076-1acef2000000",
        "x-ms-version": "2019-12-12"
	},
	"ResponseBody":{...}

Autorisation

Une autorisation est requise lors de l’appel d’une opération d’accès aux données dans stockage Azure. Vous pouvez autoriser l’opération Query Blob Contents comme décrit ci-dessous.

Le Stockage Azure prend en charge l’utilisation de Microsoft Entra ID pour autoriser les demandes de données blob. Avec Microsoft Entra ID, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder des autorisations à un principal de sécurité. Le principal de sécurité peut être un utilisateur, un groupe, un principal de service d’application ou une identité managée Azure. Le principal de sécurité est authentifié par Microsoft Entra ID pour retourner un jeton OAuth 2.0. Le jeton peut ensuite être utilisé pour autoriser une requête auprès du service BLOB.

Pour en savoir plus sur l’autorisation à l’aide de Microsoft Entra ID, consultez Autoriser l’accès aux objets blob à l’aide de Microsoft Entra ID.

Autorisations

Vous trouverez ci-dessous l’action RBAC nécessaire pour qu’un utilisateur, un groupe ou un principal de service Microsoft Entra appelle l’opérationQuery Blob Contents, ainsi que le rôle RBAC intégré Azure le moins privilégié qui inclut cette action :

Action RBAC Azure :Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rôle intégré avec privilèges minimum :Lecteur de données Blob de stockage

Pour en savoir plus sur l’attribution de rôles à l’aide d’Azure RBAC, consultez Attribuer un rôle Azure pour accéder aux données blob.

Une signature d’accès partagé (SAP) fournit un accès délégué sécurisé aux ressources d’un compte de stockage. Avec une SAP, vous disposez d’un contrôle granulaire sur la façon dont un client peut accéder aux données. Vous pouvez spécifier la ressource à laquelle le client peut accéder, les autorisations dont il dispose sur ces ressources et la durée de validité de la signature d’accès partagé.

L’opération Query Blob Contents prend en charge trois types de signatures d’accès partagé : SAP de délégation d’utilisateur, SAP de service et SAP de compte.

En guise de meilleure pratique en matière de sécurité, nous vous recommandons d’utiliser des informations d’identification Microsoft Entra plutôt que la clé de compte de stockage, qui peut être plus facilement compromise. Si votre conception d’application nécessite des signatures d’accès partagé, utilisez les informations d’identification Microsoft Entra pour créer une sap de délégation d’utilisateur, si possible.

Lorsque l’accès à la clé partagée n’est pas autorisé pour le compte de stockage, un jeton SAP de service ou un jeton SAP de compte ne sont pas autorisés lors d’une demande adressée au Stockage Blob. Pour en savoir plus, consultez Comprendre comment l’interdiction de la clé partagée affecte les jetons SAP.

SAP de délégation d’utilisateur

Une sap de délégation d’utilisateur est sécurisée avec des informations d’identification Microsoft Entra, ainsi que par les autorisations spécifiées pour la signature d’accès partagé.

L’appel de l’opération à l’aide Query Blob Contents d’un jeton SAS délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Lecture (r) dans le cadre du jeton SAP de délégation d’utilisateur.

Pour en savoir plus sur la SAP de délégation d’utilisateur, consultez Créer une SAP de délégation d’utilisateur.

SAP de service

Une SAP de service est sécurisée à l’aide de la clé de compte de stockage. Une SAP de service délègue l’accès à une ressource dans un seul service de stockage Azure, tel que le stockage d’objets blob.

L’appel de l’opération à l’aide Query Blob Contents d’un jeton SAP délégué à un conteneur ou à une ressource d’objet blob nécessite l’autorisation Lecture (r) dans le cadre du jeton SAP de service.

Pour en savoir plus sur la SAP de service, consultez Créer une SAP de service.

SAP de compte

Une SAP de compte est sécurisée à l’aide de la clé de compte de stockage. Une SAP de compte délègue l’accès aux ressources d’un ou plusieurs des services de stockage. Toutes les opérations disponibles via une SAP de service ou de délégation d’utilisateur sont également disponibles via une SAP de compte.

Le tableau suivant indique le type de ressource signé et les autorisations signées à spécifier lors de la délégation de l’accès :

Opération	Service signé	Type de ressource signé	Autorisation signée
Contenu de l’objet blob de requête	Blob (b)	Objet (o)	Lecture (r)

Pour en savoir plus sur la SAP de compte, consultez Créer une SAP de compte.

L’opération Query Blob Contents prend en charge l’autorisation de clé partagée. L’autorisation avec des clés de compte n’est pas recommandée pour la plupart des scénarios, car elle est moins sécurisée.

Microsoft recommande d’interdire l’autorisation de clé partagée pour le compte de stockage lorsque cela est possible. Pour plus d’informations, consultez Empêcher l’autorisation avec une clé partagée.

Remarques

L’opération Query Blob Contents est prise en charge uniquement sur un BlockBlob type.
L’interrogation du contenu d’un objet blob chiffré avec des clés fournies par le client n’est pas prise en charge dans cette version de l’API.
Cette opération n’est pas prise en charge sur les objets blob dans les comptes pour 20000.
L'en-tête x-ms-version est requis pour récupérer un objet blob qui appartient à un conteneur privé. Si l’objet blob appartient à un conteneur disponible pour un accès public complet ou partiel, tout client peut le lire sans spécifier de version. La version du service n’est pas requise pour récupérer un objet blob qui appartient à un conteneur public. Pour plus d'informations, consultez la page Limiter l'accès aux conteneurs et aux objets blob.
Vous pouvez utiliser l’opération pour interroger uniquement les objets dont le Query Blob Contents format est délimité/CSV ou JSON.

Facturation

Les demandes de tarification peuvent provenir de clients qui utilisent les API Stockage Blob, soit directement via l’API REST Stockage Blob, soit à partir d’une bibliothèque cliente stockage Azure. Ces demandes accumulent des frais par transaction. Le type de transaction affecte la façon dont le compte est facturé. Par exemple, les transactions de lecture s’accumulent dans une catégorie de facturation différente de celle des transactions d’écriture. Le tableau suivant montre la catégorie de facturation pour Query Blob Contents les demandes en fonction du type de compte de stockage :

Opération	Type de compte de stockage	Catégorie de facturation
Contenu de l’objet blob de requête	Objet blob de blocs Premium Usage général v2 Standard	Opérations de lecture¹

¹En plus des frais de lecture, le compte entraîne des frais pour les catégories de transactions Accélération des requêtes - Données analysées et Accélération des requêtes - Données retournées . La tarification de ces catégories s’affiche sur la page de tarification Azure Data Lake Storage.

Voir aussi

Autoriser les demandes à l’état du stockage Azure et les codes d’erreur Codes d’erreur Stockage Blob Définir des délais d’expiration pour les opérations de stockage Blob Accélération des requêtes : référence du langage SQL