요청 엔드포인트

이 페이지는 Cloud Storage에 액세스하는 데 사용할 수 있는 여러 가지 요청 엔드포인트를 설명합니다. Cloud Storage는 HTTP/1.1, HTTP/2, HTTP/3 프로토콜을 지원합니다. 엔드포인트는 URL로 작성된 Cloud Storage에 액세스할 수 있는 위치입니다.

일반적인 API 요청

JSON API

Cloud Storage에 직접 JSON API 요청을 수행할 때는 다음 엔드포인트를 사용합니다.

  • 객체 업로드를 제외한 일반적인 JSON API 요청의 경우, 다음 엔드포인트를 사용합니다. 여기에서 PATH_TO_RESOURCE를 적절한 값으로 바꿉니다.

    https://storage.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • JSON API 객체 업로드에는 다음 엔드포인트를 사용합니다. 여기에서 BUCKET_NAME를 적절한 값으로 바꿉니다.

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • 일괄 요청의 경우, 다음 엔드포인트를 사용하고 PATH_TO_RESOURCE를 적절한 값으로 바꿉니다.

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • JSON API 객체 다운로드의 경우 필요에 따라 다음 엔드포인트를 사용할 수 있습니다. 여기에서 BUCKET_NAMEOBJECT_NAME은 적절한 값으로 바꿉니다.

    https://storage.s3nsapis.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API 엔드포인트는 HTTPS 요청만 수용합니다.

XML API

Cloud Storage에 직접 XML API 요청을 수행할 때는 가상 호스팅 스타일 또는 경로 스타일의 엔드포인트를 사용하면서 BUCKET_NAMEOBJECT_NAME을 적절한 값으로 바꿉니다.

  • 가상 호스팅 스타일 엔드포인트:

    https://BUCKET_NAME.storage.s3nsapis.fr/OBJECT_NAME

  • 경로 스타일 엔드포인트:

    https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

XML API 엔드포인트는 보안 소켓 레이어(SSL) 암호화를 지원하므로 HTTP 또는 HTTPS를 사용할 수 있습니다. 특히 OAuth 2.0을 사용하여 Cloud Storage에 인증한다면 HTTPS를 사용하는 것이 좋습니다.

프록시를 통해 연결할 때의 권장 사례에 대한 문제해결 주제를 참조하세요.

URL 경로 부분 인코딩

버킷 이름 지정객체 이름 지정에 대한 일반적인 고려사항 외에도, Cloud Storage 도구 간의 호환성을 보장하기 위해 다음 문자가 요청 URL의 객체 이름 또는 쿼리 문자열에 표시되는 경우 이를 인코딩해야 합니다.

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], 공백 문자

예를 들어 example-bucket 버킷에서 foo??bar라는 객체에 JSON API GET 요청을 보내려면 요청 URL은 다음과 같아야 합니다.

GET https://storage.s3nsapis.fr/storage/v1/b/example-bucket/o/foo%3f%3fbar

나열된 문자 중 일부는 모든 시나리오에서 인코딩되지 않아야 합니다. 또한 일반적으로 Cloud Storage 클라이언트 라이브러리와 같은 클라이언트 라이브러리를 통해 인코딩이 처리되므로, 이러한 도구를 사용할 때 원시 객체 이름을 전달할 수 있습니다.

백분율 인코딩 사용에 대한 자세한 내용은 RFC 3986의 섹션 3.3 경로를 참조하세요.

Google Cloud 콘솔 엔드포인트

Google Cloud 콘솔을 사용할 때 다음 URL을 사용하여 다른 리소스에 액세스합니다.

리소스 URL
프로젝트의 버킷 목록 https://console.cloud.google.com/storage/browser?project=PROJECT_ID
버킷의 객체 목록 https://console.cloud.google.com/storage/browser/BUCKET_NAME
객체의 세부정보 https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
객체의 데이터 인증된 브라우저 다운로드를 참조하세요.

gcloud 엔드포인트

gcloud storage 명령어는 JSON API 엔드포인트를 사용합니다. 엔드포인트 사용량은 gcloud CLI에서 사용자 대신 관리합니다.

클라이언트 라이브러리 엔드포인트

Cloud Storage 클라이언트 라이브러리는 요청 엔드포인트를 자동으로 관리합니다. 선택적으로 요청 엔드포인트를 수동으로 설정할 수 있습니다. 이 옵션은 특정 엔드포인트를 사용해야 하는 경우 또는 로컬 에뮬레이터를 사용하려는 경우와 같은 테스트에 유용할 수 있습니다.

C++

자세한 내용은 Cloud Storage C++ API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

자세한 내용은 Cloud Storage C# API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.


using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

자세한 내용은 Cloud Storage Go API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

자세한 내용은 Cloud Storage Java API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.


import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

    Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).setHost(endpoint).build().getService();

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

자세한 내용은 Cloud Storage Node.js API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

자세한 내용은 Cloud Storage PHP API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

자세한 내용은 Cloud Storage Python API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.


from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

자세한 내용은 Cloud Storage Ruby API 참조 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.

코드 샘플을 실행하기 전에 GOOGLE_CLOUD_UNIVERSE_DOMAIN 환경 변수를 s3nsapis.fr으로 설정합니다.

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

인증된 브라우저 다운로드

인증된 브라우저 다운로드는 쿠키 기반 인증을 사용합니다. 쿠키 기반 인증은 사용자에게 신원 확인을 위해 사용자 계정에 로그인할 것을 요청합니다. 지정된 계정에는 객체를 다운로드할 수 있는 적절한 권한이 있어야 합니다. 예를 들어 Identity and Access Management를 사용하여 객체에 대한 액세스를 제어하는 경우 사용자의 계정에 storage.objects.viewer 권한이 있어야 합니다. 이 권한은 스토리지 객체 뷰어 역할에 부여됩니다.

쿠키 기반 인증을 사용하여 객체를 다운로드하려면 다음 URL을 사용하고 BUCKET_NAMEOBJECT_NAME을 적절한 값으로 바꿉니다.

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

예를 들어 example-maps 버킷에서 london.jpg 이미지를 공유한 경우 URL은 다음과 같습니다.

https://storage.cloud.google.com/example-maps/london.jpg

로그인에 성공하면 요청된 콘텐츠로 리디렉션됩니다. 이 콘텐츠의 URL은 영숫자 시퀀스로 시작하며 /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME 문자열을 포함합니다.

인증된 브라우저 다운로드를 수행하려면 HTTPS를 사용해야 합니다. HTTPS에 대한 HTTP 리디렉션을 사용하려고 시도합니다.

공개 객체에 액세스

storage.cloud.google.com URI에 대한 모든 요청은 인증되어야 합니다. allUsers에 객체에 액세스할 수 있는 권한이 있는 경우에도 마찬가지입니다. 사용자가 인증 없이 익명으로 액세스할 수 있는 객체를 다운로드할 수 있게 하려면 XML API 경로 스타일 엔드포인트를 사용합니다.

https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

자세한 내용과 예시는 공개 데이터 액세스를 참조하세요.

상호 TLS 지원

상호 TLS(mTLS)는 클라이언트와 서버 간의 상호 인증을 위한 업계 표준 프로토콜입니다. Cloud Storage는 다음 mTLS 엔드포인트를 지원합니다.

다음 단계