クイック スタート:Python 用 Face クライアント ライブラリQuickstart: Face client library for Python

Python 用 Face クライアント ライブラリの概要。Get started with the Face client library for Python. 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。Follow these steps to install the package and try out the example code for basic tasks. Face サービスは、画像内の人間の顔を検出および認識するための高度なアルゴリズムへのアクセスを提供します。The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Python 用 Face クライアント ライブラリを使用すると、次のことができます。Use the Face client library for Python to:

  • 画像内の顔を検出するDetect faces in an image
  • 似た顔の検索Find similar faces
  • 人物グループを作成してトレーニングするCreate and train a person group
  • 顔を識別するIdentify a face
  • 顔を確認するVerify faces
  • データ移行のためのスナップショットを作成するTake a snapshot for data migration

リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PiPy) | サンプルReference documentation | Library source code | Package (PiPy) | Samples

前提条件Prerequisites

設定Setting up

Face Azure リソースを作成するCreate a Face Azure resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用してローカル マシン上に Face 用のリソースを作成します。Create a resource for Face using the Azure portal or Azure CLI on your local machine. 次のこともできます。You can also:

試用版のサブスクリプションまたはリソースからキーを取得した後、FACE_SUBSCRIPTION_KEY という名前のキーの環境変数を作成します。After you get a key from your trial subscription or resource, create an environment variable for the key, named FACE_SUBSCRIPTION_KEY.

新しい Python アプリケーションを作成するCreate a new Python application

新しい Python スクリプト (たとえば quickstart-file.py) を作成します。Create a new Python script—quickstart-file.py, for example. 次に、それを任意のエディターまたは IDE で開き、以下のライブラリをインポートします。Then open it in your preferred editor or IDE and import the following libraries.

import asyncio
import io
import glob
import os
import sys
import time
import uuid
import requests
from urllib.parse import urlparse
from io import BytesIO
from PIL import Image, ImageDraw
from azure.cognitiveservices.vision.face import FaceClient
from msrest.authentication import CognitiveServicesCredentials
from azure.cognitiveservices.vision.face.models import TrainingStatusType, Person, SnapshotObjectType, OperationStatusType

次に、リソースの Azure エンドポイントおよびキー用の変数を作成します。Then, create variables for your resource's Azure endpoint and key. エンドポイントの最初の部分 (westus) を、自分のサブスクリプションに合わせて変更しなければならない場合があります。You may need to change the first part of the endpoint (westus) to match your subscription.

# Set the FACE_SUBSCRIPTION_KEY environment variable with your key as the value.
# This key will serve all examples in this document.
KEY = os.environ['FACE_SUBSCRIPTION_KEY']

# Set the FACE_ENDPOINT environment variable with the endpoint from your Face service in Azure.
# This endpoint will be used in all examples in this quickstart.
ENDPOINT = os.environ['FACE_ENDPOINT']

注意

アプリケーションの起動後に環境変数を作成した場合、その変数にアクセスするには、アプリケーションを実行しているエディター、IDE、またはシェルを閉じて、もう一度開く必要があります。If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable.

クライアント ライブラリをインストールするInstall the client library

次のようにして、クライアント ライブラリをインストールできます。You can install the client library with:

pip install --upgrade azure-cognitiveservices-vision-face

オブジェクト モデルObject model

以下のクラスとインターフェイスにより、Face Python SDK の主要な機能の一部が処理されます。The following classes and interfaces handle some of the major features of the Face Python SDK.

名前Name 説明Description
FaceClientFaceClient このクラスは、Face サービスを使用するための承認を表し、すべての Face 機能に必要です。This class represents your authorization to use the Face service, and you need it for all Face functionality. サブスクリプション情報を使用してこれをインスタンス化し、他のクラスのインスタンスを生成するために使用します。You instantiate it with your subscription information, and you use it to produce instances of other classes.
FaceOperationsFaceOperations このクラスは、人間の顔に対して実行できる基本的な検出と認識のタスクを処理します。This class handles the basic detection and recognition tasks that you can do with human faces.
DetectedFaceDetectedFace このクラスは、画像内の 1 つの顔から検出されたすべてのデータを表します。This class represents all of the data that was detected from a single face in an image. これを使用して、顔に関する詳細情報を取得できます。You can use it to retrieve detailed information about the face.
FaceListOperationsFaceListOperations このクラスは、クラウドに格納された FaceList コンストラクトを管理します。これには、さまざまな顔のセットが格納されます。This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonOperationsPersonGroupPersonOperations このクラスは、クラウドに格納された Person コンストラクトを管理します。これには、1 人の人物に属している顔のセットが格納されます。This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupOperationsPersonGroupOperations このクラスは、クラウドに格納された PersonGroup コンストラクトを管理します。これには、さまざまな Person オブジェクトのセットが格納されます。This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
ShapshotOperationsShapshotOperations このクラスは、スナップショット機能を管理します。これを使用すると、クラウドベースのすべての顔データを一時的に保存し、そのデータを新しい Azure サブスクリプションに移行することができます。This class manages the Snapshot functionality; you can use it to temporarily save all of your cloud-based face data and migrate that data to a new Azure subscription.

コード例Code examples

これらのコード スニペットでは、Python 用 Face クライアント ライブラリを使用して以下のタスクを実行する方法が示されています。These code snippets show you how to do the following tasks with the Face client library for Python:

クライアントを認証するAuthenticate the client

注意

このクイックスタートでは、FACE_SUBSCRIPTION_KEY という名前の、Face キーの環境変数が作成してあることを前提としています。This quickstart assumes you've created an environment variable for your Face key, named FACE_SUBSCRIPTION_KEY.

ご利用のエンドポイントとキーを使用してクライアントをインスタンス化します。Instantiate a client with your endpoint and key. キーを使用して CognitiveServicesCredentials オブジェクトを作成し、それをエンドポイントと共に使用して、FaceClient オブジェクトを作成します。Create a CognitiveServicesCredentials object with your key, and use it with your endpoint to create a FaceClient object.

# Create an authenticated FaceClient.
face_client = FaceClient(ENDPOINT, CognitiveServicesCredentials(KEY))

画像内の顔を検出するDetect faces in an image

次のコードは、リモート画像内の顔を検出します。The following code detects a face in a remote image. 検出された顔の ID をコンソールに出力し、プログラムのメモリにも格納します。It prints the detected face's ID to the console and also stores it in program memory. 次に、複数の人物が含まれている画像内の顔を検出し、それらの ID もコンソールに出力します。Then, it detects the faces in an image with multiple people and prints their IDs to the console as well. detect_with_url メソッドのパラメーターを変更することで、DetectedFace オブジェクトごとに異なる情報を返すことができます。By changing the parameters in the detect_with_url method, you can return different information with each DetectedFace object.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedy---mini-biography.jpg'
single_image_name = os.path.basename(single_face_image_url)
detected_faces = face_client.face.detect_with_url(url=single_face_image_url)
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Display the detected face ID in the first single-face image.
# Face IDs are used for comparison to faces (their IDs) detected in other images.
print('Detected face ID from', single_image_name, ':')
for face in detected_faces: print (face.face_id)
print()

# Save this ID for use in Find Similar
first_image_face_ID = detected_faces[0].face_id

その他の検出シナリオについては、GitHub 上のサンプル コードを参照してください。See the sample code on GitHub for more detection scenarios.

顔を表示してフレームに収めるDisplay and frame faces

次のコードは、指定された画像をディスプレイに出力し、DetectedFace.faceRectangle プロパティを使用して顔の周りに四角形を描画します。The following code outputs the given image to the display and draws rectangles around the faces, using the DetectedFace.faceRectangle property.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/detection1.jpg'
single_image_name = os.path.basename(single_face_image_url)
detected_faces = face_client.face.detect_with_url(url=single_face_image_url)
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Convert width height to a point in a rectangle
def getRectangle(faceDictionary):
    rect = faceDictionary.face_rectangle
    left = rect.left
    top = rect.top
    right = left + rect.width
    bottom = top + rect.height
    
    return ((left, top), (right, bottom))


# Download the image from the url
response = requests.get(single_face_image_url)
img = Image.open(BytesIO(response.content))

# For each face returned use the face rectangle and draw a red box.
print('Drawing rectangle around face... see popup for results.')
draw = ImageDraw.Draw(img)
for face in detected_faces:
    draw.rectangle(getRectangle(face), outline='red')

# Display the image in the users default image browser.
img.show()

顔の周囲に赤い四角形が描画されている若い女性

似た顔の検索Find similar faces

次のコードでは、検出された 1 つの顔を取得し、他の顔のセットを探して一致するものを見つけます。The following code takes a single detected face and searches a set of other faces to find matches. 一致するものが見つかると、一致した顔の四角形の座標がコンソールに出力されます。When it finds a match, it prints the rectangle coordinates of the matched face to the console.

一致するものを探すFind matches

最初に、上のセクション (「画像内の顔を検出する」) のコードを実行して、1 つの顔への参照を保存します。First, run the code in the above section (Detect faces in an image) to save a reference to a single face. 次に、以下のコードを実行して、グループ画像内の複数の顔への参照を取得します。Then run the following code to get references to several faces in a group image.

# Detect the faces in an image that contains multiple faces
# Each detected face gets assigned a new ID
multi_face_image_url = "http://www.historyplace.com/kennedy/president-family-portrait-closeup.jpg"
multi_image_name = os.path.basename(multi_face_image_url)
detected_faces2 = face_client.face.detect_with_url(url=multi_face_image_url)

次に、以下のコード ブロックを追加して、グループ内で最初の顔のインスタンスを探します。Then add the following code block to find instances of the first face in the group. この動作を変更する方法を学習するには、find_similar メソッドを参照してください。See the find_similar method to learn how to modify this behavior.

# Search through faces detected in group image for the single face from first image.
# First, create a list of the face IDs found in the second image.
second_image_face_IDs = list(map(lambda x: x.face_id, detected_faces2))
# Next, find similar face IDs like the one detected in the first image.
similar_faces = face_client.face.find_similar(face_id=first_image_face_ID, face_ids=second_image_face_IDs)
if not similar_faces[0]:
    print('No similar faces found in', multi_image_name, '.')

次のコードを使用して、一致の詳細をコンソールに出力します。Use the following code to print the match details to the console.

# Print the details of the similar faces detected
print('Similar faces found in', multi_image_name + ':')
for face in similar_faces:
    first_image_face_ID = face.face_id
    # The similar face IDs of the single face image and the group image do not need to match, 
    # they are only used for identification purposes in each image.
    # The similar faces are matched using the Cognitive Services algorithm in find_similar().
    face_info = next(x for x in detected_faces2 if x.face_id == first_image_face_ID)
    if face_info:
        print('  Face ID: ', first_image_face_ID)
        print('  Face rectangle:')
        print('    Left: ', str(face_info.face_rectangle.left))
        print('    Top: ', str(face_info.face_rectangle.top))
        print('    Width: ', str(face_info.face_rectangle.width))
        print('    Height: ', str(face_info.face_rectangle.height))

人物グループを作成してトレーニングするCreate and train a person group

次のコードでは、3 つの異なる Person オブジェクトを持つ PersonGroup を作成します。The following code creates a PersonGroup with three different Person objects. Person が例の画像のセットに関連付けられ、各人物を認識できるようにトレーニングが行われます。It associates each Person with a set of example images, and then it trains to be able to recognize each person.

PersonGroup を作成するCreate PersonGroup

このシナリオの手順を実行するには、プロジェクトのルート ディレクトリに画像 (https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images ) を保存する必要があります。To step through this scenario, you need to save the following images to the root directory of your project: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

この画像のグループには、3 人の異なる人物に対応する顔画像の 3 つのセットが含まれています。This group of images contains three sets of face images corresponding to three different people. このコードでは、3 つの Person オブジェクトを定義し、それらを womanman、および child で始まる画像ファイルに関連付けます。The code will define three Person objects and associate them with image files that start with woman, man, and child.

画像の設定後、作成する PersonGroup オブジェクトのために、スクリプトの先頭でラベルを定義します。Once you've set up your images, define a label at the top of your script for the PersonGroup object you'll create.

# Used in the Person Group Operations,  Snapshot Operations, and Delete Person Group examples.
# You can call list_person_groups to print a list of preexisting PersonGroups.
# SOURCE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
PERSON_GROUP_ID = 'my-unique-person-group'

# Used for the Snapshot and Delete Person Group examples.
TARGET_PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)

次に、以下のコードをスクリプトの末尾に追加します。Then add the following code to the bottom of your script. このコードでは、PersonGroup オブジェクトと 3 つの Person オブジェクトが作成されます。This code creates a PersonGroup and three Person objects.

'''
Create the PersonGroup
'''
# Create empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
print('Person group:', PERSON_GROUP_ID)
face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID)

# Define woman friend
woman = face_client.person_group_person.create(PERSON_GROUP_ID, "Woman")
# Define man friend
man = face_client.person_group_person.create(PERSON_GROUP_ID, "Man")
# Define child friend
child = face_client.person_group_person.create(PERSON_GROUP_ID, "Child")

顔を人物に割り当てるAssign faces to Persons

次のコードでは、画像をプレフィックスで並べ替え、顔を検出し、顔を各 Person オブジェクトに割り当てます。The following code sorts your images by their prefix, detects faces, and assigns the faces to each Person object.

'''
Detect faces and register to correct person
'''
# Find all jpeg images of friends in working directory
woman_images = [file for file in glob.glob('*.jpg') if file.startswith("woman")]
man_images = [file for file in glob.glob('*.jpg') if file.startswith("man")]
child_images = [file for file in glob.glob('*.jpg') if file.startswith("child")]

# Add to a woman person
for image in woman_images:
    w = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, woman.person_id, w)

# Add to a man person
for image in man_images:
    m = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, man.person_id, m)

# Add to a child person
for image in child_images:
    ch = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, child.person_id, ch)

PersonGroup をトレーニングするTrain PersonGroup

顔を割り当てたら、PersonGroup をトレーニングして、その各 Person オブジェクトに関連付けられている視覚的特徴を識別できるようにする必要があります。Once you've assigned faces, you must train the PersonGroup so that it can identify the visual features associated with each of its Person objects. 次のコードは、非同期の train メソッドを呼び出し、結果をポーリングして、状態をコンソールに出力します。The following code calls the asynchronous train method and polls the result, printing the status to the console.

'''
Train PersonGroup
'''
print()
print('Training the person group...')
# Train the person group
face_client.person_group.train(PERSON_GROUP_ID)

while (True):
    training_status = face_client.person_group.get_training_status(PERSON_GROUP_ID)
    print("Training status: {}.".format(training_status.status))
    print()
    if (training_status.status is TrainingStatusType.succeeded):
        break
    elif (training_status.status is TrainingStatusType.failed):
        sys.exit('Training the person group has failed.')
    time.sleep(5)

顔を識別するIdentify a face

次のコードは、複数の顔が含まれている画像を取得し、画像内の各人物の ID を特定します。The following code takes an image with multiple faces and looks to find the identity of each person in the image. 検出された顔はそれぞれ、顔の特徴が確認されているさまざまな Person オブジェクトのデータベース、つまり PersonGroup と比較されます。It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known.

重要

この例を実行するには、まず、「人物グループを作成してトレーニングする」のコードを実行する必要があります。In order to run this example, you must first run the code in Create and train a person group.

テスト画像を取得するGet a test image

次のコードは、プロジェクトのルートで画像 test-image-person-group.jpg を探し、画像内の顔を検出します。The following code looks in the root of your project for an image test-image-person-group.jpg and detects the faces in the image. この画像は、PersonGroup の管理に使用される画像と同じ場所 (https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images ) にあります。You can find this image with the images used for PersonGroup management: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

'''
Identify a face against a defined PersonGroup
'''
# Group image for testing against
group_photo = 'test-image-person-group.jpg'
IMAGES_FOLDER = os.path.join(os.path.dirname(os.path.realpath(__file__)))
# Get test image
test_image_array = glob.glob(os.path.join(IMAGES_FOLDER, group_photo))
image = open(test_image_array[0], 'r+b')

# Detect faces
face_ids = []
faces = face_client.face.detect_with_stream(image)
for face in faces:
    face_ids.append(face.face_id)

顔を識別するIdentify faces

identify メソッドは、検出された顔の配列を受け取り、それらを PersonGroup と比較します。The identify method takes an array of detected faces and compares them to a PersonGroup. 検出された顔を Person と照合できる場合は、結果を保存します。If it can match a detected face to a Person, it saves the result. このコードは、詳細な一致結果をコンソールに出力します。This code prints detailed match results to the console.

# Identify faces
results = face_client.face.identify(face_ids, PERSON_GROUP_ID)
print('Identifying faces in {}'.format(os.path.basename(image.name)))
if not results:
    print('No person identified in the person group for faces from {}.'.format(os.path.basename(image.name)))
for person in results:
    print('Person for face ID {} is identified in {} with a confidence of {}.'.format(person.face_id, os.path.basename(image.name), person.candidates[0].confidence)) # Get topmost confidence score

顔を確認するVerify faces

確認操作では、顔 ID と、別の顔 ID または Person オブジェクトのいずれかを取得し、同じ人に属しているかどうかを判断します。The Verify operation takes a face ID and either another face ID or a Person object and determines whether they belong to the same person.

次のコードでは、2 つのソース画像から顔を検出し、ターゲット画像から検出された顔と照らしてそれらを確認します。The following code detects faces in two source images and then verifies them against a face detected from a target image.

テスト イメージを取得するGet test images

次のコード ブロックでは、確認操作のソース画像とターゲット画像を指す変数を宣言します。The following code blocks declare variables that will point to the source and target images for the verification operation.

# Base url for the Verify and Facelist/Large Facelist operations
IMAGE_BASE_URL = 'https://csdx.blob.core.windows.net/resources/Face/Images/'
# Create a list to hold the target photos of the same person
target_image_file_names = ['Family1-Dad1.jpg', 'Family1-Dad2.jpg']
# The source photos contain this person
source_image_file_name1 = 'Family1-Dad3.jpg'
source_image_file_name2 = 'Family1-Son1.jpg'

確認対象の顔を検出するDetect faces for verification

次のコードは、ソース画像とターゲット画像から顔を検出して、それらを変数に保存します。The following code detects faces in the source and target images and saves them to variables.

# Detect face(s) from source image 1, returns a list[DetectedFaces]
detected_faces1 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name1)
# Add the returned face's face ID
source_image1_id = detected_faces1[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces1), source_image_file_name1))

# Detect face(s) from source image 2, returns a list[DetectedFaces]
detected_faces2 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name2)
# Add the returned face's face ID
source_image2_id = detected_faces2[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces2), source_image_file_name2))

# List for the target face IDs (uuids)
detected_faces_ids = []
# Detect faces from target image url list, returns a list[DetectedFaces]
for image_file_name in target_image_file_names:
    detected_faces = face_client.face.detect_with_url(IMAGE_BASE_URL + image_file_name)
    # Add the returned face's face ID
    detected_faces_ids.append(detected_faces[0].face_id)
    print('{} face(s) detected from image {}.'.format(len(detected_faces), image_file_name))

確認の結果を取得するGet verification results

次のコードでは、各ソース画像をターゲット画像と比較し、同じ人物のものであるかどうかを示すメッセージを出力します。The following code compares each of the source images to the target image and prints a message indicating whether they belong to the same person.

# Verification example for faces of the same person. The higher the confidence, the more identical the faces in the images are.
# Since target faces are the same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_same = face_client.face.verify_face_to_face(source_image1_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence)
    if verify_result_same.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence))

# Verification example for faces of different persons.
# Since target faces are same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_diff = face_client.face.verify_face_to_face(source_image2_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence)
    if verify_result_diff.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence))

データ移行のためのスナップショットを作成するTake a snapshot for data migration

スナップショット機能を使用すると、トレーニング済みの PersonGroup などの保存した顔データを別の Azure Cognitive Services Face サブスクリプションに移動できます。The Snapshots feature lets you move your saved face data, such as a trained PersonGroup, to a different Azure Cognitive Services Face subscription. この機能を利用するのは、たとえば、無料試用版サブスクリプションを使用して PersonGroup オブジェクトを作成してあり、それを有料サブスクリプションに移行することが必要になった場合などです。You may want to use this feature if, for example, you've created a PersonGroup object using a free trial subscription and now want to migrate it to a paid subscription. スナップショット機能の広範な概要については、顔データの移行に関するページを参照してください。See the Migrate your face data for a broad overview of the Snapshots feature.

この例では、「人物グループを作成してトレーニングする」で作成した PersonGroup を移行します。In this example, you will migrate the PersonGroup you created in Create and train a person group. 先にそのセクションを完了することも、独自の Face データ コンストラクトを使用することもできます。You can either complete that section first, or use your own Face data construct(s).

ターゲット サブスクリプションを設定するSet up target subscription

まず、Face リソースを含む 2 つ目の Azure サブスクリプションが必要です。そのためには、「設定」セクションの手順に従います。First, you must have a second Azure subscription with a Face resource; you can do this by following the steps in the Setting up section.

次に、スクリプトの先頭付近で以下の変数を作成します。Then, create the following variables near the top of your script. また、お使いの Azure アカウントのサブスクリプション ID と新しい (ターゲット) アカウントのキー、エンドポイント、サブスクリプション ID のための、新しい環境変数を作成する必要があります。You'll also need to create new environment variables for the subscription ID of your Azure account, as well as the key, endpoint, and subscription ID of your new (target) account.

'''
Snapshot operations variables
These are only used for the snapshot example. Set your environment variables accordingly.
'''
# Source endpoint, the location/subscription where the original person group is located.
SOURCE_ENDPOINT = ENDPOINT
# Source subscription key. Must match the source endpoint region.
SOURCE_KEY = os.environ['FACE_SUBSCRIPTION_KEY']
# Source subscription ID. Found in the Azure portal in the Overview page of your Face (or any) resource.
SOURCE_ID = os.environ['AZURE_SUBSCRIPTION_ID']
# Person group name that will get created in this quickstart's Person Group Operations example.
SOURCE_PERSON_GROUP_ID = PERSON_GROUP_ID
# Target endpoint. This is your 2nd Face subscription.
TARGET_ENDPOINT = os.environ['FACE_ENDPOINT2']
# Target subscription key. Must match the target endpoint region.
TARGET_KEY = os.environ['FACE_SUBSCRIPTION_KEY2']
# Target subscription ID. It will be the same as the source ID if created Face resources from the same 
# subscription (but moving from region to region). If they are differnt subscriptions, add the other target ID here.
TARGET_ID = os.environ['AZURE_SUBSCRIPTION_ID']
# NOTE: We do not need to specify the target PersonGroup ID here because we generate it with this example.
# Each new location you transfer a person group to will have a generated, new person group ID for that region.

ターゲット クライアントを認証するAuthenticate target client

スクリプトの後の方で、現在のクライアント オブジェクトをソース クライアントとして保存し、ターゲット サブスクリプションのために新しいクライアント オブジェクトを認証します。Later in your script, save your current client object as the source client, and then authenticate a new client object for your target subscription.

'''
Authenticate
'''
# Use your source client already created (it has the person group ID you need in it).
face_client_source = face_client
# Create a new FaceClient instance for your target with authentication.
face_client_target = FaceClient(TARGET_ENDPOINT, CognitiveServicesCredentials(TARGET_KEY))

スナップショットを使用するUse a snapshot

スナップショット操作の残りは、非同期関数内で行われます。The rest of the snapshot operations take place within an asynchronous function.

  1. 最初のステップは、スナップショットを取得することです。これにより、元のサブスクリプションの顔データが一時的なクラウドの場所に保存されます。The first step is to take the snapshot, which saves your original subscription's face data to a temporary cloud location. このメソッドは、操作の状態を照会するために使用する ID を返します。This method returns an ID that you use to query the status of the operation.

    '''
    Snapshot operations in 4 steps
    '''
    async def run():
        # STEP 1, take a snapshot of your person group, then track status.
        # This list must include all subscription IDs from which you want to access the snapshot.
        source_list = [SOURCE_ID, TARGET_ID]
        # You may have many sources, if transferring from many regions
        # remove any duplicates from the list. Passing the same subscription ID more than once causes
        # the Snapshot.take operation to fail.
        source_list = list(dict.fromkeys(source_list))
    
        # Note Snapshot.take is not asynchronous.
        # For information about Snapshot.take see:
        # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L36
        take_snapshot_result = face_client_source.snapshot.take(
            type=SnapshotObjectType.person_group,
            object_id=PERSON_GROUP_ID,
            apply_scope=source_list,
            # Set this to tell Snapshot.take to return the response; otherwise it returns None.
            raw=True
            )
        # Get operation ID from response for tracking
        # Snapshot.type return value is of type msrest.pipeline.ClientRawResponse. See:
        # https://docs.microsoft.com/en-us/python/api/msrest/msrest.pipeline.clientrawresponse?view=azure-python
        take_operation_id = take_snapshot_result.response.headers['Operation-Location'].replace('/operations/', '')
    
        print('Taking snapshot( operation ID:', take_operation_id, ')...')
    
  2. 次に、操作が完了するまでに ID を照会します。Next, query the ID until the operation has completed.

    # STEP 2, Wait for snapshot taking to complete.
    take_status = await wait_for_operation(face_client_source, take_operation_id)
    
    # Get snapshot id from response.
    snapshot_id = take_status.resource_location.replace ('/snapshots/', '')
    
    print('Snapshot ID:', snapshot_id)
    print('Taking snapshot... Done\n')
    

    このコードでは、wait_for_operation 関数が使用されます。この関数は、個別に定義する必要があります。This code makes use of the wait_for_operation function, which you should define separately:

    # Helper function that waits and checks status of API call processing.
    async def wait_for_operation(client, operation_id):
        # Track progress of taking the snapshot.
        # Note Snapshot.get_operation_status is not asynchronous.
        # For information about Snapshot.get_operation_status see:
        # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L466
        result = client.snapshot.get_operation_status(operation_id=operation_id)
    
        status = result.status.lower()
        print('Operation status:', status)
        if ('notstarted' == status or 'running' == status):
            print("Waiting 10 seconds...")
            await asyncio.sleep(10)
            result = await wait_for_operation(client, operation_id)
        elif ('failed' == status):
            raise Exception("Operation failed. Reason:" + result.message)
        return result
    
  3. 非同期関数に戻ります。Go back to your asynchronous function. apply 操作を使用して、顔データをターゲット サブスクリプションに書き込みます。Use the apply operation to write your face data to your target subscription. このメソッドも、ID を返します。This method also returns an ID.

    # STEP 3, apply the snapshot to target region(s)
    # Snapshot.apply is not asynchronous.
    # For information about Snapshot.apply see:
    # https://github.com/Azure/azure-sdk-for-python/blob/master/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/snapshot_operations.py#L366
    apply_snapshot_result = face_client_target.snapshot.apply(
        snapshot_id=snapshot_id,
        # Generate a new UUID for the target person group ID.
        object_id=TARGET_PERSON_GROUP_ID,
        # Set this to tell Snapshot.apply to return the response; otherwise it returns None.
        raw=True
        )
    apply_operation_id = apply_snapshot_result.response.headers['Operation-Location'].replace('/operations/', '')
    print('Applying snapshot( operation ID:', apply_operation_id, ')...')
    
  4. 再度 wait_for_operation 関数を使用して、操作が完了するまでに ID を照会します。Again, use the wait_for_operation function to query the ID until the operation has completed.

    # STEP 4, wait for applying snapshot process to complete.
    await wait_for_operation(face_client_target, apply_operation_id)
    print('Applying snapshot... Done\n')
    print('End of transfer.')
    print()
    

これらの手順を完了すると、新しい (ターゲット) サブスクリプションから顔データ コンストラクトにアクセスできるようになります。Once you've completed these steps, you'll be able to access your face data constructs from your new (target) subscription.

アプリケーションの実行Run the application

クイック スタート ファイルで python コマンドを使用して、アプリケーションを実行します。Run the application with the python command on your quickstart file.

python quickstart-file.py

リソースをクリーンアップするClean up resources

Cognitive Services サブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除することができます。If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。Deleting the resource group also deletes any other resources associated with it.

このクイックスタートで作成してある PersonGroup を削除したい場合は、スクリプトで次のコードを実行します。If you created a PersonGroup in this quickstart and you want to delete it, run the following code in your script:

# Delete the main person group.
face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
print("Deleted the person group {} from the source location.".format(PERSON_GROUP_ID))
print()

このクイックスタートでスナップショット機能を使用してデータを移行した場合は、ターゲット サブスクリプションに保存されている PersonGroup も削除する必要があります。If you migrated data using the Snapshot feature in this quickstart, you'll also need to delete the PersonGroup saved to the target subscription.

# Delete the person group in the target region.
face_client_target.person_group.delete(TARGET_PERSON_GROUP_ID)
print("Deleted the person group {} from the target location.".format(TARGET_PERSON_GROUP_ID))

次のステップNext steps

このクイックスタートでは、Python 用の Face ライブラリを使用して基本的なタスクを行う方法について学習しました。In this quickstart, you learned how to use the Face library for Python to do basis tasks. 次は、リファレンス ドキュメントを参照して、ライブラリの詳細について学習してください。Next, explore the reference documentation to learn more about the library.