Dateien aus Cloud Storage mit Dateisatzeinträgen anzeigen

Sie können die Data Catalog API verwenden, um Cloud Storage-Dateisatzeinträge zu erstellen und zu suchen (in diesem Dokument als „Dateisätze“ bezeichnet).

Dateisätze

Ein Cloud Storage-Dateisatz ist ein Eintrag in einer vom Nutzer erstellten Eintragsgruppe. Weitere Informationen finden Sie unter Einträge und Eintragsgruppen.

Er wird durch ein oder mehrere Dateimuster definiert, die einen Satz von einer oder mehreren Cloud Storage-Dateien angeben.

Anforderungen an Dateimuster:

  • Ein Dateimuster muss mit gs://bucket_name/ beginnen.
  • Der Bucket-Name muss den Anforderungen für Cloud Storage-Bucket-Namen entsprechen.
  • Platzhalter sind in den Ordner- und Dateibereichen von Dateimustern zulässig, in Bucket-Namen sind jedoch keine Platzhalter zulässig. Beispiele finden Sie unter:
  • Ein Dateisatz muss mindestens ein und nicht mehr als 5 Dateisatzmuster haben.

Sie können Data Catalog-Dateisätze mit Dataflow SQL abfragen, aber nur, wenn sie ein definiertes Schema haben und nur CSV-Dateien ohne Kopfzeilen enthalten.

Eintragsgruppen und Dateisätze erstellen

Dateisätze müssen in einer von Nutzern erstellten Eintragsgruppe platziert werden. Wenn Sie keine Eintragsgruppe erstellt haben, erstellen Sie zuerst die Eintragsgruppe und erstellen Sie dann den Dateisatz innerhalb der Eintragsgruppe. Sie können IAM-Richtlinien für die Eintragsgruppe festlegen, um festzulegen, wer Zugriff auf Dateisätze und andere Einträge innerhalb der Eintragsgruppe hat.

Console

Console

  1. Rufen Sie die Seite Dataplex > Eintragsgruppen auf.

    Dataplex-Eintragsgruppen aufrufen

  2. Klicken Sie auf Eintragsgruppe erstellen.

  3. Füllen Sie das Formular Eintragsgruppe erstellen aus und klicken Sie dann auf ERSTELLEN.

  4. Die Seite Eintragsgruppendetails wird geöffnet. Klicken Sie bei ausgewähltem Tab EINTRÄGE auf ERSTELLEN.

  5. Füllen Sie das Formular Dateisatz erstellen aus.

    1. Klicken Sie zum Anhängen eines Schemas auf Schema definieren, um das Schemaformular zu öffnen. Klicken Sie auf + FELDER HINZUFÜGEN, um Felder einzeln hinzuzufügen, oder klicken Sie rechts oben im Formular auf Als Text bearbeiten, um die Felder im JSON-Format anzugeben.
    2. Klicken Sie auf Speichern, um das Schema zu speichern.

  6. Klicken Sie auf Erstellen, um das Dateiset zu erstellen.

gcloud

gcloud

1. Eintragsgruppe erstellen

Verwenden Sie den Befehl gcloud data-catalog entry-groups create, um eine Eintragsgruppe mit einem angehängten Schema und einer Beschreibung zu erstellen.

Beispiel:

gcloud data-catalog entry-groups create my_entrygroup \
    --location=us-central1

2. Dateisatz innerhalb der Eintragsgruppe erstellen

Erstellen Sie mit dem Befehl gcloud data-catalog entries create einen Dateisatz innerhalb einer Eintragsgruppe. Mit diesem Google Cloud CLI-Befehl unten wird ein Dateisatzeintrag erstellt, der das Schema der Dateisatzdaten enthält.

gcloud data-catalog entries create my_fileset_entry \  
    --location=us-central1 \  
    --entry-group=my_entrygroup \  
    --type=FILESET \  
    --gcs-file-patterns=gs://my-bucket/*.csv \  
    --schema-from-file=path_to_schema_file \  
    --description="Fileset description ..."

Notizen melden:

  • --gcs-file-patterns: Siehe Anforderungen an Dateimuster.
  • --schema-from-file: Das folgende Beispiel zeigt das JSON-Format der Schematextdatei, die vom Flag --schema-from-file akzeptiert wird.
    [
  {
    "column": "first_name",
    "description": "First name",
    "mode": "REQUIRED",
    "type": "STRING"
  },
  {
    "column": "last_name",
    "description": "Last name",
    "mode": "REQUIRED",
    "type": "STRING"
  },
  {
    "column": "address",
    "description": "Address",
    "mode": "REPEATED",
    "type": "STRING"
  }
]

Java

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Java in der Data Catalog-Kurzanleitung mit Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Data Catalog Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich beim Data Catalog zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

import com.google.cloud.datacatalog.v1.ColumnSchema;
import com.google.cloud.datacatalog.v1.CreateEntryRequest;
import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.Entry;
import com.google.cloud.datacatalog.v1.EntryGroupName;
import com.google.cloud.datacatalog.v1.EntryType;
import com.google.cloud.datacatalog.v1.GcsFilesetSpec;
import com.google.cloud.datacatalog.v1.Schema;
import java.io.IOException;

// Sample to create file set entry
public class CreateFilesetEntry {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String entryGroupId = "fileset_entry_group";
    String entryId = "fileset_entry_id";
    createFilesetEntry(projectId, entryGroupId, entryId);
  }

  // Create Fileset Entry.
  public static void createFilesetEntry(String projectId, String entryGroupId, String entryId)
      throws IOException {
    // Currently, Data Catalog stores metadata in the us-central1 region.
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Construct the Entry for the Entry request.
      Entry entry =
          Entry.newBuilder()
              .setDisplayName("My Fileset")
              .setDescription("This fileset consists of ....")
              .setGcsFilesetSpec(
                  GcsFilesetSpec.newBuilder().addFilePatterns("gs://cloud-samples-data/*").build())
              .setSchema(
                  Schema.newBuilder()
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("first_name")
                              .setDescription("First name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("last_name")
                              .setDescription("Last name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("addresses")
                              .setDescription("Addresses")
                              .setMode("REPEATED")
                              .setType("RECORD")
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("city")
                                      .setDescription("City")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("state")
                                      .setDescription("State")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .build())
                      .build())
              .setType(EntryType.FILESET)
              .build();

      // Construct the Entry request to be sent by the client.
      CreateEntryRequest entryRequest =
          CreateEntryRequest.newBuilder()
              .setParent(EntryGroupName.of(projectId, location, entryGroupId).toString())
              .setEntryId(entryId)
              .setEntry(entry)
              .build();

      // Use the client to send the API request.
      Entry entryCreated = dataCatalogClient.createEntry(entryRequest);
      System.out.printf("Entry created with name: %s", entryCreated.getName());
    }
  }
}

Node.js

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Node.js in der Data Catalog-Kurzanleitung mit Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Data Catalog Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich beim Data Catalog zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function createFileset() {
  // Create a fileset within an entry group.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project';
  // const entryGroupId = 'my_entry_group';
  // const entryId = 'my_entry';

  // Currently, Data Catalog stores metadata in the us-central1 region.
  const location = 'us-central1';

  // Delete any pre-existing Entry with the same name that will be used
  // when creating the new Entry.
  try {
    const formattedName = datacatalog.entryPath(
      projectId,
      location,
      entryGroupId,
      entryId
    );
    await datacatalog.deleteEntry({name: formattedName});
  } catch (err) {
    console.log('Entry does not exist.');
  }

  // Delete any pre-existing Entry Group with the same name
  // that will be used to create the new Entry Group.
  try {
    const formattedName = datacatalog.entryGroupPath(
      projectId,
      location,
      entryGroupId
    );
    await datacatalog.deleteEntryGroup({name: formattedName});
  } catch (err) {
    console.log('Entry Group does not exist.');
  }

  // Construct the Entry Group for the Entry Group request.
  const entryGroup = {
    displayName: 'My Fileset Entry Group',
    description: 'This Entry Group consists of ....',
  };

  // Construct the Entry Group request to be sent by the client.
  const entryGroupRequest = {
    parent: datacatalog.locationPath(projectId, location),
    entryGroupId: entryGroupId,
    entryGroup: entryGroup,
  };

  // Use the client to send the API request.
  await datacatalog.createEntryGroup(entryGroupRequest);

  // Construct the Entry for the Entry request.
  const FILESET_TYPE = 4;

  const entry = {
    displayName: 'My Fileset',
    description: 'This fileset consists of ....',
    gcsFilesetSpec: {filePatterns: ['gs://my_bucket/*']},
    schema: {
      columns: [
        {
          column: 'city',
          description: 'City',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'state',
          description: 'State',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'addresses',
          description: 'Addresses',
          mode: 'REPEATED',
          subcolumns: [
            {
              column: 'city',
              description: 'City',
              mode: 'NULLABLE',
              type: 'STRING',
            },
            {
              column: 'state',
              description: 'State',
              mode: 'NULLABLE',
              type: 'STRING',
            },
          ],
          type: 'RECORD',
        },
      ],
    },
    type: FILESET_TYPE,
  };

  // Construct the Entry request to be sent by the client.
  const request = {
    parent: datacatalog.entryGroupPath(projectId, location, entryGroupId),
    entryId: entryId,
    entry: entry,
  };

  // Use the client to send the API request.
  const [response] = await datacatalog.createEntry(request);

  console.log(`Name: ${response.name}`);
  console.log(`Display name: ${response.displayName}`);
  console.log(`Type: ${response.type}`);
}
createFileset();

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python in der Data Catalog-Kurzanleitung mit Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Data Catalog Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich beim Data Catalog zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

# Import required modules.
from google.cloud import datacatalog_v1

# TODO: Set these values before running the sample.
project_id = "project_id"
fileset_entry_group_id = "entry_group_id"
fileset_entry_id = "entry_id"

# For all regions available, see:
# https://cloud.google.com/data-catalog/docs/concepts/regions
location = "us-central1"

datacatalog = datacatalog_v1.DataCatalogClient()

# Create an Entry Group.
entry_group_obj = datacatalog_v1.types.EntryGroup()
entry_group_obj.display_name = "My Fileset Entry Group"
entry_group_obj.description = "This Entry Group consists of ...."

entry_group = datacatalog.create_entry_group(
    parent=datacatalog_v1.DataCatalogClient.common_location_path(
        project_id, location
    ),
    entry_group_id=fileset_entry_group_id,
    entry_group=entry_group_obj,
)
print(f"Created entry group: {entry_group.name}")

# Create a Fileset Entry.
entry = datacatalog_v1.types.Entry()
entry.display_name = "My Fileset"
entry.description = "This fileset consists of ...."
entry.gcs_fileset_spec.file_patterns.append("gs://my_bucket/*.csv")
entry.type_ = datacatalog_v1.EntryType.FILESET

# Create the Schema, for example when you have a csv file.
entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="first_name",
        description="First name",
        mode="REQUIRED",
        type_="STRING",
    )
)

entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="last_name", description="Last name", mode="REQUIRED", type_="STRING"
    )
)

# Create the addresses parent column
addresses_column = datacatalog_v1.types.ColumnSchema(
    column="addresses", description="Addresses", mode="REPEATED", type_="RECORD"
)

# Create sub columns for the addresses parent column
addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="city", description="City", mode="NULLABLE", type_="STRING"
    )
)

addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="state", description="State", mode="NULLABLE", type_="STRING"
    )
)

entry.schema.columns.append(addresses_column)

entry = datacatalog.create_entry(
    parent=entry_group.name, entry_id=fileset_entry_id, entry=entry
)
print(f"Created fileset entry: {entry.name}")

REST und Befehlszeile

REST

Wenn Sie keinen Zugriff auf Cloud Client-Bibliotheken für Ihre Sprache haben oder die API mit REST-Anfragen testen möchten, sehen Sie sich die folgenden Beispiele an und lesen Sie die Dokumentation zu den Data Catalog REST APIs entryGroups.create und entryGroups.entries.create.

  1. Eintragsgruppe erstellen

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project-id: Ihre Google Cloud-Projekt-ID
  • entryGroupId: Die ID muss mit einem Buchstaben oder Unterstrich beginnen, darf nur lateinische Buchstaben, Zahlen und Unterstriche enthalten und darf höchstens 64 Zeichen umfassen.
  • displayName: Der Textname für die Eintragsgruppe.

HTTP-Methode und URL:

POST https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId

JSON-Text anfordern:

{
  "displayName": "Entry Group display name"
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "name": "projects/my_projectid/locations/us-central1/entryGroups/my_entry_group",
  "displayName": "Entry Group display name",
  "dataCatalogTimestamps": {
    "createTime": "2019-10-19T16:35:50.135Z",
    "updateTime": "2019-10-19T16:35:50.135Z"
  }
}
  1. Dateisatz innerhalb der Eintragsgruppe erstellen

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • project_id: Ihre Google Cloud-Projekt-ID
  • entryGroupId: ID der vorhandenen entryGroup. Dateisatz wird in dieser sntryGroup erstellt.
  • entryId: EntryId des neuen Dateisatzes. Die ID muss mit einem Buchstaben oder Unterstrich beginnen, darf nur lateinische Buchstaben, Zahlen und Unterstriche enthalten und darf höchstens 64 Zeichen umfassen.
  • description: Dateisatzbeschreibung.
  • displayName: Der Textname für den Dateisatzeintrag.
  • filePatterns: Muss mit "gs://bucket_name/" beginnen. Siehe Anforderungen an Dateimuster.
  • schema: Dateisatzschema.

    Beispiel für ein JSON-Schema:
    { ...
  "schema": {
    "columns": [
      {
        "column": "first_name",
        "description": "First name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "last_name",
        "description": "Last name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "address",
        "description": "Address",
        "mode": "REPEATED",
        "subcolumns": [
          {
            "column": "city",
            "description": "City",
            "mode": "NULLABLE",
            "type": "STRING"
          },
          {
            "column": "state",
            "description": "State",
            "mode": "NULLABLE",
            "type": "STRING"
          }
        ],
        "type": "RECORD"
      }
    ]
  }
...
}

HTTP-Methode und URL:

POST https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId

JSON-Text anfordern:

{
  "description": "Fileset description.",
  "displayName": "Display name",
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://bucket_name/file_pattern"
    ]
  },
  "type": "FILESET",
  "schema": { schema }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "name": "projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id",
  "type": "FILESET",
  "displayName": "My Fileset",
  "description": "My Fileset description.",
  "schema": {
    "columns": [
      {
        "type": "STRING",
        "description": "First name",
        "mode": "REQUIRED",
        "column": "first_name"
      },
      {
        "type": "STRING",
        "description": "Last name",
        "mode": "REQUIRED",
        "column": "last_name"
      },
      {
        "type": "RECORD",
        "description": "Address",
        "mode": "REPEATED",
        "column": "address",
        "subcolumns": [
          {
            "type": "STRING",
            "description": "City",
            "mode": "NULLABLE",
            "column": "city"
          },
          {
            "type": "STRING",
            "description": "State",
            "mode": "NULLABLE",
            "column": "state"
          }
        ]
      }
    ]
  },
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://my_bucket_name/chicago_taxi_trips/csv/shard-*.csv"
    ]
  },
  "sourceSystemTimestamps": {
    "createTime": "2019-10-23T23:11:26.326Z",
    "updateTime": "2019-10-23T23:11:26.326Z"
  },
"linkedResource": "//datacatalog.googleapis.com/projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id"
}

IAM-Rollen, -Berechtigungen und -Richtlinien

Data Catalog definiert „entry“- und „entryGroup“-Rollen, um die Berechtigungsverwaltung für Dateisätze und andere Data Catalog-Ressourcen zu erleichtern.

Beitragsrollen Beschreibung
dataCatalog.entryOwner Inhaber eines bestimmten Eintrags oder einer Gruppe von Einträgen.
  • Berechtigungen:
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • Gültigkeit:
    • Organisations-, Projekt- und entryGroup-Ebene
dataCatalog.entryViewer Kann Details zu Eintrag und entryGroup anzeigen.
  • Berechtigungen
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Gültigkeit:
    • Organisations-, Projekt- und entryGroup-Ebene
Rollen für Eintragsgruppen Beschreibung
dataCatalog.entryGroupOwner Inhaber einer bestimmten entryGroup.
  • Berechtigungen:
    • datacatalog.entryGroups.(*)
    • datacatalog.entries.(*)
  • Gültigkeit:
    • Organisations-, Projekt- und entryGroup-Ebene
dataCatalog.entryGroupCreator Kann entryGroups in einem Projekt erstellen. Dem Ersteller einer entryGroup wird automatisch die Rolle dataCatalog.entryGroupOwner zugewiesen.
  • Berechtigungen:
    • datacatalog.entryGroups.(get | create)
  • Gültigkeit:
    • Organisations- und Projektebene

IAM-Richtlinien festlegen

Nutzer mit der Berechtigung datacatalog.<resource>.setIamPolicy können IAM-Richtlinien für Data Catalog-Eintragsgruppen und andere Data Catalog-Ressourcen festlegen (siehe Data Catalog-Rollen).

Console

Rufen Sie in der Data Catalog-UI die Seite Details der Eintragsgruppe auf und verwenden Sie dann das IAM-Steuerfeld auf der rechten Seite, um Berechtigungen zu erteilen oder zu entziehen.

gcloud

Rollen für Eintragsgruppen zuweisen

Beispiel 1

Ein Unternehmen mit unterschiedlichen Geschäftskontexten für seine Dateisätze erstellt separate Eintragsgruppen order-files und user-files:

Die Gruppe „order-files“ enthält Speichergruppen mit Dateien für stornierte und abgeschlossene Bestellungen, während die Gruppe „user-files“ einen Speicherbereich mit Dateien mit personenidentifizierbaren Informationen enthält.
Abbildung 1. Beispiel für das Speichern von Bestelldaten und Nutzerdaten in verschiedenen Eintragsgruppen

Das Unternehmen gewährt Nutzern die Rolle „Betrachter von Eintragsgruppen“ für order-files, das heißt, sie können nur nach Einträgen suchen, die in dieser Eintragsgruppe enthalten sind. Ihre Suchergebnisse geben keine Einträge in der Eintragsgruppe user-files zurück.

Beispiel 2

Ein Unternehmen gewährt nur einem Nutzer im Projekt project_entry_group die Rolle „Betrachter der Eintragsgruppe“. Der Nutzer kann nur Einträge innerhalb dieses Projekts ansehen.

In Dateisätzen suchen

Nutzer können den Umfang der Suche in Data Catalog mithilfe des Attributs type einschränken. type=entry_group beschränkt die Suchanfrage auf Eintragsgruppen, während type=fileset nur nach Dateisätzen sucht. type-Attribute können in Verbindung mit anderen Attributen wie projectid verwendet werden.

gcloud

  • Nach Eintragsgruppen in einem Projekt suchen:

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "projectid=my-project type=entry_group"

  • Suchen Sie nach allen Beitragsgruppen, auf die Sie zugreifen können:

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=entry_group"

  • Nach Dateisätzen in einem Projekt suchen:

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=entry.fileset"

  • Suche nach Dateisätzen in einem Projekt (vereinfachte Syntax): 

    gcloud data-catalog search \  
    --include-project-ids=my-project
    "type=fileset"