Migrazione semplice da Amazon S3 a Cloud Storage

Questa pagina descrive come completare una migrazione semplice da Amazon Simple Storage Service (Amazon S3) a Cloud Storage. In una migrazione semplice, utilizzi gli strumenti e le librerie esistenti per generare richieste REST autenticate ad Amazon S3 per inviare invece richieste autenticate a Cloud Storage.

Eseguire la migrazione da Amazon S3 a Cloud Storage in uno scenario di migrazione semplice

Per effettuare richieste a Cloud Storage, devi completare i seguenti passaggi:

Utilizza l'intestazione x-amz-project-id header quando effettui richieste per creare ed elencare i bucket.

Ottieni una chiave HMAC (Hash-based Message Authentication Code).

Nelle librerie o negli strumenti esistenti, apporta le seguenti modifiche:

• Modifica l'endpoint della richiesta in modo che utilizzi l'endpoint della richiesta dell'API XML di Cloud Storage .
• Sostituisci la chiave di accesso e la chiave segreta di Amazon Web Services (AWS) con l'ID di accesso e il secret di Cloud Storage corrispondenti (chiamati collettivamente chiave HMAC di Cloud Storage).

• Assicurati che le intestazioni x-amz- utilizzino i valori di Cloud Storage supportati. Ad esempio, x-amz-storage-class deve utilizzare una delle classi di archiviazione di Cloud Storage disponibili.

  Quando utilizzi l'API XML di Cloud Storage in uno scenario di migrazione semplice, la specifica dell'identificatore della firma AWS nell'intestazione Authorization indica a Cloud Storage di prevedere le intestazioni x-amz-* e la sintassi XML degli ACL di Amazon S3 nella richiesta. Cloud Storage elabora le intestazioni x-amz-* che hanno un x-goog-* equivalente, come quelle elencate nella tabella delle intestazioni, ed elabora l'intestazione x-amz-decoded-content-length.

Dopo aver apportato queste modifiche, puoi iniziare a utilizzare gli strumenti e le librerie esistenti per inviare richieste HMAC a Cloud Storage.

Ad esempio, gli esempi seguenti mostrano come elencare i bucket Cloud Storage utilizzando l'SDK Amazon S3:

Go

Per saperne di più, consulta la documentazione di riferimento dell'API Go Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"
	"io"
	"time"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/credentials"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/s3"
)

func listGCSBuckets(w io.Writer, googleAccessKeyID string, googleAccessKeySecret string) error {
	// googleAccessKeyID := "Your Google Access Key ID"
	// googleAccessKeySecret := "Your Google Access Key Secret"

	// Create a new client and do the following:
	// 1. Change the endpoint URL to use the Google Cloud Storage XML API endpoint.
	// 2. Use Cloud Storage HMAC Credentials.
	sess := session.Must(session.NewSession(&aws.Config{
		Region:      aws.String("auto"),
		Endpoint:    aws.String("https://storage.googleapis.com"),
		Credentials: credentials.NewStaticCredentials(googleAccessKeyID, googleAccessKeySecret, ""),
	}))

	client := s3.New(sess)
	ctx := context.Background()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	result, err := client.ListBucketsWithContext(ctx, &s3.ListBucketsInput{})
	if err != nil {
		return fmt.Errorf("ListBucketsWithContext: %w", err)
	}

	fmt.Fprintf(w, "Buckets:")
	for _, b := range result.Buckets {
		fmt.Fprintf(w, "%s\n", aws.StringValue(b.Name))
	}

	return nil
}

Java

Per saperne di più, consulta la documentazione di riferimento dell'API JavaCloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.Bucket;
import java.util.List;

public class ListGcsBuckets {
  public static void listGcsBuckets(String googleAccessKeyId, String googleAccessKeySecret) {

    // String googleAccessKeyId = "your-google-access-key-id";
    // String googleAccessKeySecret = "your-google-access-key-secret";

    // Create a BasicAWSCredentials using Cloud Storage HMAC credentials.
    BasicAWSCredentials googleCreds =
        new BasicAWSCredentials(googleAccessKeyId, googleAccessKeySecret);

    // Create a new client and do the following:
    // 1. Change the endpoint URL to use the Google Cloud Storage XML API endpoint.
    // 2. Use Cloud Storage HMAC Credentials.
    AmazonS3 interopClient =
        AmazonS3ClientBuilder.standard()
            .withEndpointConfiguration(
                new AwsClientBuilder.EndpointConfiguration(
                    "https://storage.googleapis.com", "auto"))
            .withCredentials(new AWSStaticCredentialsProvider(googleCreds))
            .build();

    // Call GCS to list current buckets
    List<Bucket> buckets = interopClient.listBuckets();

    // Print bucket names
    System.out.println("Buckets:");
    for (Bucket bucket : buckets) {
      System.out.println(bucket.getName());
    }

    // Explicitly clean up client resources.
    interopClient.shutdown();
  }

Python

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Python.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import boto3  # type: ignore


def list_gcs_buckets(
    google_access_key_id: str, google_access_key_secret: str
) -> List[str]:
    """Lists all Cloud Storage buckets using AWS SDK for Python (boto3)
    Positional arguments:
        google_access_key_id: hash-based message authentication code (HMAC) access ID
        google_access_key_secret: HMAC access secret

    Returned value is a list of strings, one for each bucket name.

    To use this sample:
    1. Create a Cloud Storage HMAC key: https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create
    2. Change endpoint_url to a Google Cloud Storage XML API endpoint.

    To learn more about HMAC: https://cloud.google.com/storage/docs/authentication/hmackeys#overview
    """
    client = boto3.client(
        "s3",
        region_name="auto",
        endpoint_url="https://storage.googleapis.com",
        aws_access_key_id=google_access_key_id,
        aws_secret_access_key=google_access_key_secret,
    )

    # Call GCS to list current buckets
    response = client.list_buckets()

    # Return list of bucket names
    results = []
    for bucket in response["Buckets"]:
        results.append(bucket["Name"])
        print(bucket["Name"])  # Can remove if not needed after development
    return results

Specificare un'intestazione del progetto

Nelle richieste che richiedono di specificare un progetto, utilizza l' x-amz-project-id intestazione.

Tieni presente che Amazon S3 non ha progetti, quindi, a seconda degli strumenti o delle librerie client che utilizzi, la specifica di un'intestazione x-amz-project-id potrebbe non essere un'opzione.

Utilizzare le chiavi HMAC

Per utilizzare l'API XML di Cloud Storage in uno scenario di migrazione semplice, usa le chiavi HMAC (Hash-based Message Authentication Code) di Cloud Storage per le credenziali. In genere, devi creare una chiave HMAC associata a un account di servizio; in alternativa, puoi utilizzare una chiave associata a un account utente.

Eseguire l'autenticazione in uno scenario di migrazione semplice

Utilizzare l'intestazione Authorization

Per le operazioni in uno scenario di migrazione semplice che richiedono l'autenticazione, includi un'intestazione della richiesta Authorization proprio come fai per le richieste ad Amazon S3. La sintassi dell'intestazione Authorization per una richiesta Amazon S3 è:

Authorization: AWS4-HMAC-SHA256 Credential=AWS-ACCESS-KEY/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

In uno scenario di migrazione semplice, devi solo modificare l'intestazione in modo che utilizzi l'ID di accesso HMAC di Cloud Storage e assicurarti che la Signature che alleghi venga calcolata con la chiave segreta HMAC di Cloud Storage:

Authorization: ALGORITHM Credential=GOOG-ACCESS-ID/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

Le parti dell'intestazione Authorization sono:

• ALGORITHM: l'algoritmo e la versione della firma che stai utilizzando. L'utilizzo di AWS4-HMAC-SHA256 indica che stai utilizzando una firma HMAC V4 e che intendi inviare intestazioni x-amz-*. Puoi anche utilizzare GOOG4-HMAC-SHA256, che indica che stai utilizzando una firma HMAC V4 e che intendi inviare intestazioni x-goog-*, o GOOG4-RSA-SHA256, che indica che stai utilizzando una firma RSA V4 e che intendi inviare intestazioni x-goog-*.

• GOOG-ACCESS-ID: l'ID di accesso identifica l'entità che sta effettuando e firmando la richiesta. In una migrazione semplice, sostituisci l'ID della chiave di accesso di Amazon Web Service (AWS) che utilizzi per accedere ad Amazon S3 con l'ID di accesso HMAC di Cloud Storage. L'ID di accesso HMAC di Cloud Storage inizia con GOOG.

• CREDENTIAL_SCOPE: l'ambito delle credenziali, come definito nella firma. In una migrazione semplice, non devi modificare l'ambito delle credenziali se utilizzi AWS4-HMAC-SHA256 per il valore ALGORITHM.

• SIGNED_HEADERS: un elenco separato da punti e virgole dei nomi delle intestazioni che devono essere incluse per firmare questa richiesta. Tutte le intestazioni devono essere in minuscolo e ordinate in base al codice carattere.

  Un esempio di stringa di intestazione firmata in stile Amazon S3 è il seguente:

  content-type;host;x-amz-date

  In una migrazione semplice, non devi apportare modifiche alla stringa di intestazione firmata.

• SIGNATURE: la firma che consente di essere autenticata. In una migrazione semplice, sostituisci le informazioni della chiave di accesso AWS con le informazioni equivalenti della chiave HMAC di Cloud Storage.

Richiesta di autenticazione di esempio

Gli esempi seguenti caricano un oggetto denominato /europe/france/paris.jpg in un bucket denominato my-travel-maps, applicano l'ACL predefinito public-read e definiscono un'intestazione di metadati personalizzata per i revisori. Di seguito è riportata la richiesta a un bucket in Amazon S3:

PUT europe/france/paris.jpg HTTP/1.1
Host: my-travel-maps.s3.amazonaws.com
Date: Mon, 11 Mar 2019 23:46:19 GMT
Content-Length: 888814
Content-Type: image/jpg
x-amz-acl: public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer: joe,jane
Authorization: AWS4-HMAC-SHA256 Credential=AWS-ACCESS-KEY/20190311/us-east-1/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-acl;x-amz-date;x-amz-meta-reviewer, Signature=SIGNATURE

Di seguito è riportata la richiesta per un bucket in Cloud Storage:

PUT europe/france/paris.jpg HTTP/1.1
Host: my-travel-maps.storage.
Date: Mon, 11 Mar 2019 23:46:19 GMT
Content-Length: 888814
Content-Type: image/jpg
x-amz-acl: public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer: joe,jane
Authorization: AWS4-HMAC-SHA256 Credential=GOOG-ACCESS-ID/20190311/us-east-1/s3/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-acl;x-amz-date;x-amz-meta-reviewer, Signature=SIGNATURE

Di seguito è riportata la richiesta canonica corrispondente creata per questa richiesta:

PUT
/europe/france/paris.jpg

content-length:888814
content-type:image/jpg
host:my-travel-maps.storage.
x-amz-acl:public-read
x-amz-date:20190311T192918Z
x-amz-meta-reviewer:joe,jane

content-length,content-type,host,x-amz-acl,x-amz-date,x-amz-meta-reviewer
82e3da8b3f35989512e8d428add7eca73ab0e5f36586e66fbad8e1051343cbd2

Di seguito è riportata la stringa da firmare corrispondente creata per questa richiesta:

AWS4-HMAC-SHA256
20190311T192918Z
20190311/us-east-1/s3/aws4_request
73918a5ff373d7a03e406fbf9ea35675396b06fca2af76c27a5c451fa783ef65

Questa richiesta non ha fornito un'intestazione Content-MD5, quindi nella seconda riga del messaggio viene visualizzata una stringa vuota.

Controllo dell'accesso in uno scenario di migrazione semplice

Per supportare le migrazioni semplici, Cloud Storage accetta gli ACL prodotti da Amazon S3. In uno scenario di migrazione semplice, utilizzi AWS come identificatore della firma, che indica a Cloud Storage di prevedere la sintassi degli ACL utilizzando la sintassi XML degli ACL di Amazon S3. Devi assicurarti che gli ACL di Amazon S3 che utilizzi siano mappati al modello ACL di Cloud Storage. Ad esempio, se gli strumenti e le librerie utilizzano la sintassi degli ACL di Amazon S3 per concedere l'autorizzazione WRITE del bucket, allora devono anche concedere l'autorizzazione READ del bucket perché le autorizzazioni di Cloud Storage sono concentriche. Non è necessario specificare le autorizzazioni WRITE e READ quando concedi l'autorizzazione WRITE utilizzando la sintassi di Cloud Storage.

Cloud Storage supporta la sintassi degli ACL di Amazon S3 nei seguenti scenari:

• In una richiesta a Cloud Storage per recuperare gli ACL (ad esempio, una richiesta GET Object o GET Bucket), Cloud Storage restituisce la sintassi degli ACL di Amazon S3.
• In una richiesta a Cloud Storage per applicare gli ACL (ad esempio, una richiesta PUT Object o PUT Bucket), Cloud Storage prevede di ricevere la sintassi degli ACL di Amazon S3.

L'intestazione Authorization in uno scenario di migrazione semplice utilizza AWS per l'identificatore della firma, ma con l'ID di accesso HMAC di Cloud Storage.

Authorization: AWS4-HMAC-SHA256 Credential=GOOG-ACCESS-ID/CREDENTIAL_SCOPE, SignedHeaders=SIGNED_HEADERS, Signature=SIGNATURE

L'esempio seguente mostra una richiesta GET a Cloud Storage per restituire gli ACL di un oggetto.

GET europe/france/paris.jpg?acl HTTP/1.1
Host: my-travel-maps.storage.
Date: Thu, 21 Feb 2019 23:50:10 GMT
Content-Type: application/xml
X-Amz-Date: 20190221T235010Z
Authorization: AWS4-HMAC-SHA256 Credential=GOOGMC5PDPA5JLZYQMHQHRAX/20190221/region/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=29088b1d6dfeb2549f6ff67bc3744abb7e45475f0ad60400485805415bbfc534

La risposta alla richiesta include l'ACL utilizzando la sintassi degli ACL di Amazon S3.

<?xml version='1.0' encoding='UTF-8'?>
<AccessControlPolicy>
    <Owner>
        <ID>00b4903a972faa8bcce9382686e9129676f1cd6e5def1f5663affc2ba4652490
        </ID>
        <DisplayName>OwnerName</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
                xsi:type='CanonicalUser'>
                <ID>00b4903a972faa8bcce9382686e9129676f1cd6e5def1f5663affc2ba4652490</ID>
                <DisplayName>UserName</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

L'esempio seguente mostra una richiesta PUT a Cloud Storage per impostare gli ACL di un oggetto. L'esempio mostra un corpo della richiesta con la sintassi degli ACL di Amazon S3.

PUT europe/france/paris.jpg?acl HTTP/1.1
Host: my-travel-maps.storage.
Date: Thu, 21 Feb 2019 23:50:10 GMT
Content-Type: application/xml
Content-Length: 337
X-Amz-Date: 20190221T235010Z
Authorization: AWS4-HMAC-SHA256 Credential=GOOGMC5PDPA5JLZYQMHQHRAX/20190221/region/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=29088b1d6dfeb2549f6ff67bc3744abb7e45475f0ad60400485805415bbfc534

<?xml version='1.0' encoding='utf-8'?>
<AccessControlPolicy>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AmazonCustomerByEmail">
        <EmailAddress>example-service-account@example-project.</EmailAddress>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Infine, in uno scenario di migrazione semplice, puoi anche utilizzare l'identificatore della firma GOOG1 nell'intestazione Authorization. In questo caso, devi utilizzare la sintassi degli ACL di Cloud Storage e assicurarti che tutte le intestazioni x-amz-* vengano modificate in x-goog-*. Sebbene sia possibile, ti consigliamo di scegliere una migrazione completa per sfruttare tutti i vantaggi di Cloud Storage.

Supporto per la compatibilità dell'API XML con Amazon S3

Per le discussioni sull'interoperabilità dell'API XML, consulta Stack Overflow utilizzando il tag google-cloud-storage.