G-gen の佐々木です。当記事では、Google Cloud で新規プロジェクトを作成する際の注意点として、プロジェクト ID 重複に関する仕様について解説します。

プロジェクトの識別情報について
新規プロジェクト作成時に ID が重複していた場合の動作
- コンソールからプロジェクトを作成する場合
- コンソール以外からプロジェクトを作成する場合
ID の重複を事前に知ることはできない
プロジェクト ID 重複エラーを想定した実装

プロジェクトの識別情報について

Google Cloud のプロジェクトを識別するための情報としては、プロジェクト名、プロジェクト ID、プロジェクト番号の3種類があります。このうち、Google Cloud の全利用者のどのプロジェクトと重複してはいけない（グローバルに一意となる）ものはプロジェクト ID とプロジェクト番号の2つです。

識別情報	一意性	説明
プロジェクト ID	グローバルに一意	プロジェクト作成時にユーザー側で指定できる。プログラムからの操作時に対象プロジェクト指定に使用されることが多い
プロジェクト番号	グローバルに一意	プロジェクト作成時に自動で払い出され、ユーザー側では指定できない。デフォルトのサービスアカウントなどリソース ID の一部として使用されることがある
プロジェクト名	なし	表示名（display name）と呼ばれることもある。同じ組織、フォルダ内でも重複可能

参考：プロジェクトの作成と管理

新規プロジェクト作成時に ID が重複していた場合の動作

コンソールからプロジェクトを作成する場合

Google Cloud コンソールで新規プロジェクトを作成する場合、プロジェクト名を入力すると、プロジェクト ID が自動で決定されます。このとき「編集」を押下することでユーザー側で変更することもできます。

入力されたプロジェクト名がそのままプロジェクト ID として使用できない、つまりグローバルに一意になっていない場合は、{プロジェクト名}-{ランダムの数字} という形式で、グローバルに一意の ID が提案されます。

コンソール以外からプロジェクトを作成する場合

gcloud コマンドや REST API、クライアントライブラリなど、コンソール以外の方法でプロジェクトを作成する場合、任意のプロジェクト ID を指定して作成リクエストを送信しますが、プロジェクト ID が重複している場合はエラーとなります。

コンソールからプロジェクトを作成する場合のように、指定した ID が使用できない場合に、自動で一意の ID を使用してくれるような仕組みはありません。

たとえば、gcloud projects create コマンドでプロジェクトを作成する際、プロジェクト ID に重複がある場合は以下のようなエラーが返ります。

$ gcloud projects create myproject
ERROR: (gcloud.projects.create) Project creation failed. The project ID you specified is already in use by another project. Please try an alternative ID.

ID の重複を事前に知ることはできない

コンソール以外からプロジェクトを作成する場合、たとえばスクリプトを用いて自動でプロジェクトを作成したい場合などでは、「まず ID が現在使われていないか検索し、使われていなければその ID でプロジェクトを作成」すればよいと考えるかもしれませんが、これは上手くいきません。

プロジェクトに関する操作を行うことができる Resource Manager API のうち、特定のプロジェクトの検索に使用できるメソッドは projects.get と projects.search の2種類があります。それぞれ gcloud コマンドの gcloud projects describe と gcloud alpha projects search と対応しています。

gcloud projects describe コマンドで使用されていないプロジェクト ID を検索した場合、以下のようなエラーが返ってきます。

$ gcloud projects describe {使用されてないプロジェクトID}
ERROR: (gcloud.projects.describe) [example@g-gen.co.jp] does not have permission to access projects instance [{使用されてないプロジェクトID}] (or it may not exist): The caller does not have permission. This command is authenticated as example@g-gen.co.jp which is the active account specified by the [core/account] property

エラーメッセージに does not have permission to access projects instance [{使用されてないプロジェクトID}] (or it may not exist) とあるように、「指定した ID のプロジェクトに対するアクセス権がない」ため失敗したのか、「指定した ID のプロジェクトが存在しない」ため失敗したのか判別できなくなっています。REST API を直接叩いた場合は、どちらのケースでもステータスコード 403 が返ります。

次に、gcloud alpha projects search コマンドを使用する場合の例です。

$ gcloud alpha projects search --query="projectId={使用されてないプロジェクトID}"
（空のレスポンス）

search コマンドは「コマンドを実行したユーザーがアクセスできる範囲内で検索する」仕様になっており、「アクセス権のないプロジェクトの ID を検索した場合」と「存在しないプロジェクト ID を検索した場合」のどちらも空のレスポンスが返ってきます。REST API を直接叩いた場合、どちらのケースでもステータスコード 200 が返るようになっています。

このように、あるプロジェクト ID が現在使用されているか調べようとしても、API の仕様により「その ID を持つプロジェクトが存在していてアクセス権がない」ケースと「その ID を持つプロジェクトが存在しない」ケースの識別ができません。

プロジェクト ID 重複エラーを想定した実装

スクリプトを用いてプロジェクトを払い出す仕組みを開発する場合は、ID 重複時のエラーを想定した実装にする必要があります。

たとえば以下の Python コードでは、実行時にプロジェクト ID を入力し、ID 重複によりプロジェクトの作成が失敗すると、別の ID を入力するように要求しています。

from google.cloud import resourcemanager_v3
from google.api_core.exceptions import AlreadyExists
  
import sys, time
  
  
def create_project(project_id: str) -> bool:
    """
    引数の ID を元にプロジェクトを作成する
  
    Args:
        project_id (str): プロジェクト ID
  
    Returns:
        bool: プロジェクト作成の成否
    """
    client = resourcemanager_v3.ProjectsClient()
  
    request = resourcemanager_v3.CreateProjectRequest(
        project=resourcemanager_v3.Project(
            project_id=project_id,
            display_name=project_id,
        )
    )
  
    try:
        operation = client.create_project(request=request)
        print("Create project requested.")
  
        while not operation.done():
            print("Waiting for project creation...")
            time.sleep(5)
        print("Create Project succeeded.")
            
        return True
    
    # プロジェクト ID 重複時の例外処理
    except AlreadyExists:
        print(f"Project ID {project_id} is already exists.")
        return False
    
    except Exception as e:
        raise Exception(e)
    
  
if __name__ == "__main__":
    id = input("Enter new project ID: ")
    try:
        while not create_project(id):
            # プロジェクト作成が成功するまで別の ID の入力を要求する
            id = input("Enter another project ID: ")
            
    except Exception as e:
        print(f"Create project failed. {e}")
        sys.exit(1)
    
    print(f"Project {id} created.")
    sys.exit(0)